> ## Documentation Index
> Fetch the complete documentation index at: https://docs.isofold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Errors

> Diagnose and resolve the most common issues encountered when using Isofold.

## 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`:

```bash theme={null}
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:

```bash theme={null}
export ISOFOLD_VERIFY_MODE=true
```

* Downgrade to safe rewrite mode:

```bash theme={null}
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:

```bash theme={null}
export ISOFOLD_LOG_LEVEL=debug
```

Check logs for:

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

***

Still stuck? See [Debugging Tips](/troubleshooting/debugging) or [Contact Support](mailto:support@isofold.com).