Skip to content

troubleshooting.md

Latest commit

 

History

History
131 lines (82 loc) · 5.52 KB

troubleshooting.md

File metadata and controls

131 lines (82 loc) · 5.52 KB
icon screwdriver-wrench
description Solutions to common issues with the Spice.ai Cloud Platform.

Troubleshooting

Authentication & API Keys

API requests return 401 Unauthorized

  • Verify you're using the correct API key for your app. Each app has its own keys — find them in the Portal under your app's settings.
  • If you recently regenerated a key, the old key is immediately invalidated. Update all clients to use the new key.
  • Ensure the API key is passed correctly:
    • HTTP API: Include the X-API-Key header.
    • Arrow Flight: Pass the key as the password in the handshake.
    • SDKs: Set the key in the client configuration.

API key rotation without downtime

Each app has two API keys. To rotate without downtime:

  1. Regenerate Key 2 (while all clients use Key 1).
  2. Update all clients to use Key 2.
  3. Regenerate Key 1.

See API Keys for details.

SQL Queries

Query returns table not found

  • Check identifier casing. Spice normalizes unquoted SQL identifiers to lowercase (PostgreSQL-style). If your source table uses mixed-case names like MyTable, you must double-quote it in queries:

    SELECT * FROM "MyTable"

  • Confirm the dataset is configured in your app's Spicepod and the app has been deployed.

  • Ensure the data connector credentials (secrets) are correct and the source is accessible.

Query times out or is slow

  • Use data acceleration. Accelerated datasets are cached locally and queries run significantly faster. See Data Acceleration.
  • Use LIMIT to reduce result set size during development.
  • Use Arrow Flight instead of HTTP for large result sets — it has no row-count limits and streams results efficiently.
  • Apply ORDER BY with LIMIT/OFFSET when retrieving large datasets in chunks. See Best Practices.

HTTP SQL API returns truncated results

The HTTP SQL API has row and timeout limits. If you're hitting these:

  • Use the Arrow Flight API or an SDK for unlimited streaming results.
  • Add LIMIT and OFFSET clauses to paginate results.

Data Connectors

Data connector fails to connect

  • Verify the connection credentials are stored as secrets in your app and referenced correctly in the Spicepod using ${secrets:SECRET_NAME} syntax.
  • Confirm the data source is network-accessible from Spice.ai Cloud (check firewalls, IP allowlists, VPC peering).
  • Check the Data Connectors documentation for connector-specific configuration requirements.

Data refresh fails with schema mismatch

Spice infers the dataset schema at deployment time. If the source schema has changed (columns added, removed, or types changed):

  1. Redeploy the app to re-infer the schema.

The accelerated table will be re-initialized with the updated schema on redeployment.

Object store connector: file_format errors

When connecting to object stores (S3, ABFS, etc.):

  • Folder paths require an explicit file_format parameter (e.g., parquet, csv).
  • File paths can auto-detect the format from the file extension.

AI & Models

AI chat returns errors or empty responses

  • Confirm a model is configured in your app's Spicepod and the app is deployed.
  • Ensure the model provider API key (e.g., OpenAI, Anthropic) is stored as a secret and referenced correctly.
  • After adding or changing a secret, redeploy the app — secret changes don't take effect until the next deployment.

Model not available or not responding

  • Check the model name matches a supported model from your configured model provider.
  • Verify the provider's API is operational (e.g., check OpenAI's status page).
  • Review request logs in the Portal Monitoring for error details.

Secrets

Secret value is not accessible after saving

This is by design. Secret values are write-only — they cannot be retrieved after saving for security reasons. To change a secret value:

  1. Delete the existing secret.
  2. Create a new secret with the same name and the updated value.
  3. Redeploy the app.

Changes to secrets not taking effect

Secret changes require a new deployment before they take effect. After updating secrets, trigger a new deployment in the Portal.

Deployments

App is paused

On the Community Plan, applications that receive no API requests for 7 consecutive days are automatically paused. To restore:

  1. Go to your app in the Portal.
  2. Resume the app.

Paid plans do not auto-pause.

Arrow Flight

TLS/SSL certificate errors on macOS or Windows

If you encounter certificate verification errors when connecting via Arrow Flight:

  • Set the GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable to point to your system's CA bundle.
  • On macOS: export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/cert.pem
  • Or use an SDK that handles TLS configuration automatically.

Still stuck?

  • Search the FAQ for your question.
  • Ask in Slack for community support.
  • Enterprise plans include priority support with an SLA.