> For the complete documentation index, see [llms.txt](https://jacksonkasi.gitbook.io/tablecraft/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://jacksonkasi.gitbook.io/tablecraft/core-concepts/6-errors.md).

# Errors

The TableCraft Engine includes a robust error handling system. It validates all inputs (filters, sorts, selections) and throws typed errors that you can catch and return as proper HTTP responses.

## 1. Input Validation

The engine automatically validates all incoming parameters against your schema.

* **Unknown Fields:** If a user tries to filter/sort by a field that doesn't exist or isn't enabled in the config, the engine throws a `FieldError`.
* **Type Mismatch:** If a user tries to filter a `number` column with a string like "abc", the engine throws a `ValidationError`.
* **Hidden Fields:** Users cannot select or filter by hidden columns.

## 2. Error Types

The engine exports several error classes that extend `TableCraftError`.

| Error Class         | Code               | Description                                                       | HTTP Status |
| ------------------- | ------------------ | ----------------------------------------------------------------- | ----------- |
| `ValidationError`   | `VALIDATION_ERROR` | Invalid input format (e.g., "abc" for a number).                  | 400         |
| `FieldError`        | `FIELD_ERROR`      | Invalid field name (unknown, hidden, or not sortable/filterable). | 400         |
| `ConfigError`       | `CONFIG_ERROR`     | Invalid table configuration (developer error).                    | 400         |
| `DialectError`      | `DIALECT_ERROR`    | Feature not supported by the current database dialect.            | 400         |
| `QueryError`        | `QUERY_ERROR`      | Database query failed (e.g., constraint violation).               | 500         |
| `AccessDeniedError` | `ACCESS_DENIED`    | User lacks permission (RBAC).                                     | 403         |
| `NotFoundError`     | `NOT_FOUND`        | Resource not found.                                               | 404         |

## 3. Handling Errors in Your Framework

You should wrap your engine calls in a try-catch block and return appropriate HTTP responses.

{% tabs %}
{% tab title="Hono Example" %}

```typescript
import { TableCraftError } from '@tablecraft/engine';

app.onError((err, c) => {
  if (err instanceof TableCraftError) {
    return c.json({
      error: {
        code: err.code,
        message: err.message,
        details: err.details // specific field errors
      }
    }, err.statusCode);
  }

  // Handle unknown errors
  console.error(err);
  return c.json({ error: 'Internal Server Error' }, 500);
});
```

{% endtab %}

{% tab title="Response Format" %}
If a user requests `GET /products?sort=invalid_column`, they will receive:

```json
{
  "error": {
    "code": "FIELD_ERROR",
    "message": "Field 'invalid_column' is not sortable",
    "details": {
      "field": "invalid_column"
    }
  }
}
```

{% endtab %}
{% endtabs %}

## 4. Dialect Awareness

The engine automatically detects your database dialect (PostgreSQL, MySQL, SQLite) and adjusts its behavior.

{% columns %}
{% column %}
**Case Sensitivity**

* **Postgres:** Uses `ILIKE` for case-insensitive search.
* **MySQL/SQLite:** Falls back to `LIKE` (often naturally case-insensitive depending on collation).
  {% endcolumn %}

{% column %}
**Feature Support**

If a feature is only available on certain databases, the engine throws a `DialectError` instead of sending a query that will fail with a cryptic database error.

**Example — `first` subquery on MySQL:**

```
DialectError: 'first' is not supported on mysql.
Use PostgreSQL or write a raw query.
```

`'first'` mode uses `row_to_json()`, which is PostgreSQL-only. `'count'` and `'exists'` work on all dialects.
{% endcolumn %}
{% endcolumns %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://jacksonkasi.gitbook.io/tablecraft/core-concepts/6-errors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.