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

# Troubleshooting

> Diagnose installation, authorization, input, execution, usage, and destination failures without blind retries.

[Human guide: work with your agent →](https://deepline.com/docs/human/troubleshooting.md)

Identify the failed boundary before repeating a request. Preserve the command,
run or execution identity, and returned error. A timeout is not proof of no work.

## 1. Check installation

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
command -v deepline
deepline --version
deepline doctor --json
```

Run these in the actual agent environment. A CLI installed on your laptop may
not exist in a remote sandbox.
Follow [the installation guide](https://code.deepline.com/INSTALL.md) when setup
is incomplete. Let an existing setup or authorization flow finish first.
If installation is missing, paste this into your agent:

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Install and set up the official Deepline CLI globally from npm (package: deepline) by following https://code.deepline.com/INSTALL.md.
```

## 2. Check the effective workspace

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline auth status --json
deepline org status --json
```

Compare the workspace and credential source with the current folder.
Use [folder bindings](https://deepline.com/docs/sdk-v2/multi-org.md) to correct a mismatch.

CLI authorization does not export `DEEPLINE_API_KEY` into your shell.
A raw HTTP caller needs its own supported server-side credential setup.
Do not print keys into logs to diagnose this difference.

## 3. Separate discovery from input errors

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline search "your intended outcome" --type tools,prebuilts --json
```

Describe the returned identifier before execution. Check required fields, input
types, column mappings, and access mode. Do not invent an ID from a provider name.

For custom source, use `deepline plays check <file>`.
For CSV failures, use [file validation](https://deepline.com/docs/guides/validate-incoming-csv-files.md).
Do not build a retry sample by splitting physical lines with `head`.

## 4. Inspect existing work

For a Play, inspect the saved run:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline runs get <run-id> --full --json
deepline runs logs <run-id> --json
```

Use [Run logs and events](https://deepline.com/docs/sdk-v2/run-events.md) for filters and retained payloads.
For a direct call, use [execution recovery](https://deepline.com/docs/sdk-v2/tool-execution-recovery.md).

A completed run can return a legitimate no-result. A failed provider request
has a different meaning. Preserve that distinction before changing sources.

## 5. Reconcile usage separately

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline billing usage --run-id <run-id> --json
deepline billing usage --request-id <job_id> --json
```

Choose the form for the operation you started. Do not combine the two scopes.
Pending or missing amounts do not establish zero usage.
Workspace balance changes can include other callers.

For credit or cap failures, follow the returned recovery action.
Do not silently change to another paid route or remove a workspace cap.

## 6. Diagnose connections and external writes

A provider 401 or 403 indicates an access problem, not an empty dataset.
Check the intended workspace connection and the selected action's requirements.
Only owners and admins can connect integrations through the supported flow.

A write timeout can leave an uncertain destination outcome. Read and reconcile
that state before repeating the mutation. A successful connection does not
prove that every property update is allowed.

Use [Integrations](https://deepline.com/docs/integrations.md), [CRM repair](https://deepline.com/docs/guides/crm-data-quality-automation.md),
and [Production integration](https://deepline.com/docs/sdk-v2/production-integration.md) for the specific path.

## 7. Diagnose Database access

A successful empty query means no returned matches under that query.
A permission error means the statement did not establish those data facts.

Use [Query Database](https://deepline.com/docs/database-access.md) for permitted customer SQL.
Customer-owned tables and Deepline-managed views have different write rules.
A direct Postgres integration uses its own connected database and permissions.

## 8. Prepare a useful report

Record the expected result, observed result, operation, and exact error.
Keep the relevant run or execution identity for a targeted follow-up.
Exclude credentials and unrelated customer records.

> [!TIP]
>
> The report identifies the failed boundary and whether work may already exist.
> It does not substitute an empty result, zero charge, or a fresh run for
> uncertainty.

Ask your agent which evidence supports its diagnosis. If the answer is unclear,
inspect the existing work before making another paid or mutating request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.