Troubleshooting

Common issues and how to resolve them.

Table not found after sync

What it means: Your sync completed and data was written to S3, but the table is not showing up in the Lakehouse or query editor.

Why it happens: After data is written to S3, each table must be registered in the Nessie catalog to become queryable. If the catalog was temporarily unavailable or the registration request failed, the data is safe on S3 but invisible to the query engine.

What to do:

1. Go to Connections and click on the connection
2. Check the most recent sync in the history - if it says "Not queryable", the catalog registration failed
3. Click "Retry catalog registration" to re-attempt without re-syncing data
4. If retry succeeds, your tables will appear in the Lakehouse immediately

Query returns stale data

What it means: Your query results don't reflect the latest sync. You see old data even though a sync completed successfully.

Why it happens: The query engine caches table metadata for performance. Normally it detects updated metadata automatically, but if the catalog registration for the latest sync failed, the engine still sees the old version.

What to do:

1. Check the sync history for the connection - look for a recent sync that shows "Not queryable"
2. Click "Retry catalog registration" to register the latest data
3. Re-run your query - the engine will pick up the new metadata automatically

If the sync history shows "Queryable" and you still see stale data, click "Refresh" in the query editor's schema browser to reload the table list.

Sync shows error

What it means: One or more tables failed during the sync. The connection status shows error.

Why it happens: Common causes include:

• Credentials expired or revoked - API tokens (Stripe, HubSpot, Salesforce) can expire. Database passwords can be rotated.
• Source unreachable - the database server or API endpoint is down or blocking your IP
• Permission changes - the database user no longer has SELECT access on certain tables
• Schema change - a table or column was renamed or removed at the source

What to do:

1. Check the error message in the sync history - it shows which tables failed and why
2. Fix the underlying issue (update credentials, check network, restore permissions)
3. Use "Test Connection" to verify the fix
4. Re-run the sync - tables that succeeded previously still have their data, only failed tables need re-syncing

Partial failures are possible: some tables may sync successfully while others fail. Successfully synced tables are still queryable.

Connection test fails

What it means: rawquery cannot reach your data source with the provided credentials.

What to do:

• Database connections (PostgreSQL, MySQL) - verify the host, port, database name, username, and password. Ensure the rawquery server IP is allowed in your firewall or security group rules.
• API connections (Stripe, HubSpot, Salesforce, Shopify) - verify your API key or OAuth token is valid and has the required scopes
• Google Sheets - ensure the sheet is shared with the service account email shown during setup