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

# Troubleshooting

> Diagnose workspace, build, deployment, automation, record, and agent failures in a reliable order.

<Warning>
  **Limited Release.** The EDK is currently in limited release and is not available to all customers. Commands, generated file layouts, and package APIs may change before general availability. Confirm you're on the latest EDK version before starting new projects.
</Warning>

Troubleshoot from the workspace outward. Confirm the target first, then isolate authoring and deployment failures before investigating records, automations, or agents. This order reduces unnecessary live changes and keeps each conclusion tied to evidence.

The examples assume the organization workspace selects one matching saved profile. See [Authentication](/edk/authentication) if the target is ambiguous.

Use the `/elementum-debug` coding-agent playbook when you want an assistant to follow this evidence-first sequence. See [Playbooks](/edk/playbooks).

Before running commands, capture:

* The exact action that failed.
* The expected and actual results.
* The profile and App namespace.
* When the behavior last worked.
* Any record, automation execution, or conversation identifier.

Do not edit source until the evidence identifies the failing layer.

## 1. Confirm the Profile and Workspace

Run from the affected organization workspace:

```bash theme={null}
elementum auth status
elementum playbooks status
```

Confirm that the profile's instance and organization match the workspace path. If the workspace is new or its generated references may be stale, verify that it was bootstrapped with:

```bash theme={null}
elementum pull org --data-only
```

Classify an early failure as one of:

* Authentication or permissions.
* Profile and workspace mismatch.
* Missing workspace setup.
* Stale organization references.
* Missing or incomplete App or Element source.

Pull the affected App or Element before editing an existing deployed object:

```bash theme={null}
elementum pull app <namespace>
# or
elementum pull element <namespace>
```

Review pull diagnostics and skipped items. Do not continue as though an unsupported part of the solution is managed by the generated source.

## 2. Isolate Typecheck and Build

Run the validation layers separately:

```bash theme={null}
npx tsc --noEmit
elementum build
```

If typecheck fails:

1. Fix the first causal error rather than every downstream error.
2. Confirm builder imports use public `@elementumai/edk` subpaths.
3. Confirm cross-entity references come from `@catalog`.
4. Refresh the organization or owning App when an expected catalog token is missing.
5. Do not use a broad cast, guessed token, UUID, or generated-file edit to silence the error.

If build fails, use the source path and diagnostic in the output. A build diagnostic can mean that valid TypeScript contains an option the current deployment path cannot represent safely. Remove or change it only when that matches the intended behavior; otherwise report the limitation.

Do not edit `org.ts`, `generated/catalog.ts`, `.tf/in/`, or `.tf/out/` to repair a typecheck or build failure. Refresh or regenerate those paths with their owning commands.

## 3. Isolate Plan and Apply

After typecheck and build pass:

```bash theme={null}
elementum plan
```

Separate:

* Authentication or workspace selection failures.
* Backend or deployment state failures.
* Invalid authored configuration.
* An unexplained create, replacement, or removal.
* A difference that was authored correctly but has not been applied.

If the plan shows known deployed objects as new, stop. The deployment state binding may be missing or stale. Restore the workspace and state from the approved source, or re-pull the affected App and Element to connect them. Do not apply a plan that would recreate known live objects.

If a plan succeeds but live behavior is stale, confirm that the intended plan was applied and that any required automation revision or publication change was included. Never apply a speculative fix. Review the plan and obtain approval first.

After an approved apply, run a fresh plan and confirm that no unintended changes remain.

## 4. Inspect Records and Automations

When deployment is current, inspect live data:

```bash theme={null}
elementum records list <app-namespace> \
  --limit 10 --json

elementum interventions list <app-namespace> \
  --status OPEN --json
```

Compare the stored record with the expected trigger inputs and final business result. Confirm field values, status or stage, relationships, files, and validation behavior.

For an automation failure, begin with the execution timeline:

```bash theme={null}
elementum automations status <app-namespace> \
  "<automation-name>" --latest --timeline
```

Then inspect only the failed action:

```bash theme={null}
elementum automations status <app-namespace> \
  "<automation-name>" --latest-failure --io "<action-name>" --json
```

Compare the trigger data, action input, action output, persisted record state, and expected business outcome. Expand to the complete input and output report only when the failing boundary remains unclear:

```bash theme={null}
elementum automations status <app-namespace> \
  "<automation-name>" --latest --all-io --json
```

This sequence distinguishes a trigger problem from an action problem, a persistence problem, or a downstream integration problem.

## 5. Inspect Agents and Tools

Reproduce an agent failure with one minimal turn:

```bash theme={null}
elementum chat "<agent-name>" \
  -m "<minimal reproduction>"

elementum conversation "<agent-name>" \
  <conversation-id> --json
```

Determine which layer failed:

* Routing to the intended agent or capability.
* Agent instructions or confirmation boundaries.
* Tool selection.
* Tool inputs.
* The automation or service behind the tool.
* Returned data.
* Interpretation of the result in the final response.
* Multi-turn context.

If a file is involved, reproduce with the same file type and a representative size by adding `-a <path>`. Verify the tool call and its effect independently; a reasonable final response does not prove that the correct tool ran.

When an agent delegates work, inspect the delegated result separately from the parent agent's use of that result.

## Verify the Fix

State one evidence-backed root cause and the smallest layer that owns it. After changing source, rerun:

```bash theme={null}
npx tsc --noEmit
elementum plan
```

`plan` builds the current source automatically. After an approved apply, repeat the original record, automation, or conversation reproduction. Add one adjacent regression check that could have been affected by the fix.

Report:

* Root cause and owning layer.
* Evidence used to reach the conclusion.
* The change made.
* Validation and live verification results.
* Any remaining uncertainty or untested boundary.