# 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](https://spice.ai).
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](https://spice.ai/slack) for community support.
* [Enterprise plans](https://github.com/spicehq/docs/blob/trunk/pricing/plans.md) include priority support with an SLA.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.spice.ai/help/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.