## 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](https://github.com/spicehq/docs/blob/trunk/portal/apps/api-keys.md) 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](https://github.com/spicehq/docs/blob/trunk/portal/apps/api-keys.md) 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:
  
  ```sql
  SELECT * FROM "MyTable"
  ```
* Confirm the dataset is configured in your app's [Spicepod](https://github.com/spicehq/docs/blob/trunk/portal/app-spicepod/spicepod-configuration.md) 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](https://github.com/spicehq/docs/blob/trunk/features/data-acceleration/README.md).
* **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](https://github.com/spicehq/docs/blob/trunk/best-practices.md).

#### 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](https://github.com/spicehq/docs/blob/trunk/api/sql-query/apache-arrow-flight-api.md) or an [SDK](https://github.com/spicehq/docs/blob/trunk/sdks/python-sdk/README.md) 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](https://github.com/spicehq/docs/blob/trunk/portal/apps/secrets.md) 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](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/README.md) 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](https://github.com/spicehq/docs/blob/trunk/features/ai-gateway.md) 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](https://github.com/spicehq/docs/blob/trunk/portal/apps/secrets.md) 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](https://github.com/spicehq/docs/blob/trunk/building-blocks/model-providers/README.md).
* Verify the provider's API is operational (e.g., check OpenAI's status page).
* Review request logs in the [Portal Monitoring](https://github.com/spicehq/docs/blob/trunk/portal/monitoring-and-request-logs.md) 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](https://github.com/spicehq/docs/blob/trunk/portal/app-spicepod/deployments.md).

### Deployments

#### App is paused

On the [Community Plan](https://github.com/spicehq/docs/blob/trunk/pricing/community.md), applications that receive no API requests for 7 consecutive days are automatically paused. To restore:

1. Go to your app in the [Portal](/content/site-root.html).
2. Resume the app.

[Paid plans](https://github.com/spicehq/docs/blob/trunk/pricing/plans.md) 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](https://github.com/spicehq/docs/blob/trunk/getting-started/faq.md) for your question.
* Ask in [Slack](/content/slack/index.html) for community support.
* [Enterprise plans](https://github.com/spicehq/docs/blob/trunk/pricing/plans.md) include priority support with an SLA.