Troubleshooting

Solutions to common issues with the Spice.ai Cloud Platform.

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.