> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aethis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common problems and how to resolve them.

## Decision gives an unexpected result

**Symptoms:** `aethis_decide` returns `not_eligible` when you expect `eligible`, or vice versa.

**Steps:**

1. Call `aethis_explain` (or `aethis explain -b <ruleset_id>` in the CLI) to see human-readable descriptions of the compiled rules. Check that the rules match your source text.
2. Call `aethis_decide` with `include_trace: true`. The trace shows exactly which criterion failed and why.
3. If the rules are wrong, add a guidance hint pointing to the specific clause that was missed, then `aethis_refine`.

```
aethis_decide({
  ruleset_id: "my_section:20260416-abc123",
  field_values: { ... },
  include_trace: true,
  include_explanation: true
})
```

***

## Undetermined outcome

**What it means:** The engine received the input fields but could not reach a definitive decision — the case falls outside the compiled rules or a required field was not provided.

**When to expect it:**

* A required field was missing from `field_values`
* The source legislation has a discretionary clause ("may be granted", "at the authority's discretion") — Aethis compiles these as `undetermined` rather than guessing
* The case involves a combination of values not covered by any rule

**How to handle it in your application:**

* `undetermined` means flag for human review, not auto-reject
* Check `fields_evaluated` vs `fields_provided` — if they differ, a field was unrecognised or missing
* Use `aethis_next_question` to find out what additional information the engine needs

***

## Updating rules after publishing

Published rulesets are locked — this is intentional. To update:

1. `aethis_generate_and_test` on the same project (adds a new ruleset version)
2. Refine with `aethis_refine` until all tests pass
3. `aethis_publish` — auto-deprecates the previous active ruleset

The old ruleset remains accessible by its specific ruleset ID. Systems pointing to `latest_active` automatically use the new version.

***

## Generation timeout (504)

Don't re-trigger — the server keeps running after your client disconnects. See [Handling generation timeouts](/authoring/rule-generation#handling-generation-timeouts) for the recovery flow.

***

## DATE field type error

`Date` fields take an ISO `"YYYY-MM-DD"` string or an integer ordinal on ruleset evaluations (ISO accepted since engine 0.31.0); rulebook evaluations still require ordinals. Details and conversion snippet: [Date field values](/reference/errors#date-field-values).

***

## "API key is required" on decision tools

Decision tools (`aethis_decide`, `aethis_schema`, `aethis_next_question`, `aethis_explain`) require **no API key**. If you see this error on a decision tool:

* Check that you're calling a decision tool, not an authoring tool
* Make sure `AETHIS_API_KEY` is not set to an invalid value (empty string counts)

***

## "Ruleset not found" (404)

* Verify the ruleset ID format: `section_id:YYYYMMDD-xxxxxxxx`
* Call `aethis_list_projects` → `aethis_list_rulesets` to find valid IDs
* Check the ruleset hasn't been archived

***

## "Cannot publish: tests failing"

All tests must pass before publishing. Options:

* Fix rules with `aethis_refine` and feedback pointing to the missed clause
* Use `aethis_explain_failure` to get a targeted diagnosis for a specific failing case
* Pass `force: true` to publish anyway (not recommended for production)

***

## Rate limit exceeded (429)

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "retry_after": 1714000000
}
```

Wait until the `X-RateLimit-Reset` timestamp, then retry. Contact [eng@aethis.ai](mailto:eng@aethis.ai) to increase your tier.

<Note>
  **Help improve this page**

  If something here is unclear or missing an example, use the feedback button at the bottom of the page.

  Found a bug? [Open a GitHub issue](https://github.com/Aethis-ai/feedback/issues). Evaluating Aethis for a regulated workflow? [Contact us directly](https://aethis.ai/developer-access).
</Note>