​
Overview

Isofold is designed to be transparent and non-disruptive. Still, integration issues or edge cases may occur. This guide lists the most common errors and how to resolve them.

​
Proxy connection fails

Symptom: Client returns a 502/503 or cannot connect to Isofold.

Causes:

  • Proxy URL is incorrect or unresolvable
  • TLS termination misconfigured
  • Self-hosted instance not running

​
Fixes:

  • Double-check your apiEndpoint or JDBC URL
  • Test proxy with curl or psql:
curl https://myteam.proxy.isofold.com/health
  • For self-hosted: ensure the container is listening and reachable
  • Check DNS propagation if using a custom domain

​
Query fails with warehouse error

Symptom: You receive a native BigQuery/Snowflake/Aurora error like “invalid field” or “unexpected token.”

Causes:

  • Isofold rewrite emitted a query that’s invalid in your warehouse
  • Warehouse version mismatch
  • Aggressive rewrite mode enabled

​
Fixes:

  • Enable verification mode and compare original vs rewritten query:
export ISOFOLD_VERIFY_MODE=true
  • Downgrade to safe rewrite mode:
export ISOFOLD_REWRITE_LEVEL=safe
  • Report persistent rewrite issues to support with trace ID

​
Query results differ unexpectedly

Symptom: You suspect the output of a rewritten query differs from the original.

Causes:

  • Semantic edge case in rewrite logic
  • Non-deterministic query (e.g., ORDER BY RAND())

​
Fixes:

  • Use /verify endpoint or dashboard to compare outputs
  • Disable rewriting for this query class using a passthrough rule
  • Open a ticket with the full query text and trace ID

​
BigQuery dry-run errors

Symptom: You see errors about dry-run mode failing or unsupported statements.

Causes:

  • DDL/DML queries (e.g., CREATE TABLE, MERGE) are not dry-runnable
  • BigQuery API quota exceeded

​
Fixes:

  • Skip rewrite for DDL/DML operations
  • Use an allowlist or guard clause in client config
  • Retry after cooldown or increase quota in GCP

​
Debug tips

Set verbose logging in your proxy:

export ISOFOLD_LOG_LEVEL=debug

Check logs for:

  • Query fingerprint
  • Rewritten SQL
  • Trace IDs
  • Warehouse response metadata

Still stuck? See Debugging Tips or Contact Support.