Skip to main content

Troubleshooting

This page covers the most common issues you may encounter when using Zingle, organized by category. Each entry includes what happened, why, and how to fix it.

GitHub and pull requests​

ACCESS_TOKEN_REQUIRED when creating a PR​

Cause: The GitHub connection for the selected repository doesn't have a valid access token stored.

Fix:

  1. Go to Connections → Repositories
  2. Disconnect the affected repository
  3. Reconnect with a valid personal access token (must have repo scope)
  4. Retry the PR creation from Data Pipelines, Semantic Layer, or Compute Optimization

REPO_NOT_FOUND when creating a PR​

Cause: The repository ID used in the request doesn't belong to the current workspace, or the repository was deleted on GitHub.

Fix:

  1. Verify the repo is still listed under Connections → Repositories
  2. If missing, reconnect the repository
  3. Retry from the UI

Repository sync stays in "In Progress"​

Cause: The sync process may have stalled due to a large repository, network issues, or permission problems.

Fix:

  1. Wait a few minutes — large repos can take time to index
  2. Click Sync again to trigger a fresh scan
  3. Check that your access token has read access to the repository

Snowflake​

SNOWFLAKE_AUTH_FAILED​

Cause: Snowflake rejected the username/password combination during connection validation.

Fix:

  1. In Connections → Snowflake, click Disconnect and then reconnect
  2. Double-check your username and password
  3. Verify the user has been granted the specified role, warehouse, database, and schema

SNOWFLAKE_INVALID_ACCOUNT​

Cause: The Snowflake account identifier is malformed — wrong region suffix, extra domain, or typo.

Fix:

  1. Copy the account identifier from Snowflake → Admin → Account Details
  2. Do not include .snowflakecomputing.com
  3. Save and retry the connection

SNOWFLAKE_RESOURCE_NOT_FOUND​

Cause: The specified warehouse, database, or schema doesn't exist, or the configured role doesn't have access.

Fix:

  1. Log into Snowflake and verify each resource exists
  2. Confirm the role has USAGE on the warehouse, database, and schema
  3. Reconnect in Zingle with corrected values

SNOWFLAKE_CONNECTION_TIMEOUT​

Cause: Zingle couldn't reach Snowflake within the 30-second timeout window.

Fix:

  1. Check network connectivity (VPN, firewall, security groups)
  2. Verify the Snowflake account is active and not suspended
  3. Try again — transient network issues can cause timeouts

Airflow​

AIRFLOW_TIMEOUT​

Cause: The Airflow API didn't respond within the expected timeframe.

Fix:

  1. Verify the Airflow instance is running
  2. Check the base URL is correct (including protocol and port)
  3. Look for reverse proxies or load balancers that might add latency

AIRFLOW_CONNECTION_FAILED​

Cause: The provided Airflow URL is unreachable or invalid.

Fix:

  1. Test the URL in a browser or via curl from the same network
  2. Verify authentication credentials
  3. Check that the API endpoint is exposed and not behind a VPN without access

AI modeling workspace​

The "Raise PR" button is disabled​

Cause: Not all quality gates have been satisfied. The button requires:

GateWhat to check
Schemas acceptedEvery intermediate and gold table schema must be accepted
SQL acceptedSQL for each table must be reviewed and accepted
Tests handledAll suggested tests must be accepted or rejected
Compute engine setA compute engine must be assigned to the pipeline
Schedule definedAn execution schedule must be configured

Fix: Use the lineage canvas to visit each table and ensure all tabs (Schema, SQL, Tests, Schedule) show a completed state.

Lineage is empty after describing a requirement​

Cause: The AI flow hasn't fully processed your input, or the connected repository hasn't finished syncing.

Fix:

  1. Wait for the assistant to respond with its first schema/plan message
  2. Click the relevant Accept actions to advance the workflow
  3. Check Connections → Repositories to ensure sync status is Success

AI generates incorrect SQL​

Cause: Missing or incomplete modeling guidelines, or the requirement description was too vague.

Fix:

  1. Open Settings and add detailed Modeling guidelines (naming conventions, layer rules, join policies)
  2. Add Custom instructions to fine-tune AI behavior
  3. Provide more specific requirements in the chat, including source table names and expected columns

General issues​

Page loads but shows no data​

Cause: Session expired or backend connectivity issue.

Fix:

  1. Refresh the page
  2. If the issue persists, log out and log back in
  3. Check that the Zingle backend service is running

Changes aren't syncing to the app​

Cause: Browser cache or stale state.

Fix:

  1. Hard refresh the browser (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows)
  2. Clear browser cache and cookies for the Zingle domain
  3. Retry the operation