# Find errors with the diagnostics hub

> An AI agent reads every error, warning and note your DiceyTable tab collected in one call, then checks only what is new after each change it makes.

- Question: How does an agent find errors in my game?
- Source: https://diceytable.com/docs/ai-agents/workflows/diagnostics
- Last verified: 2026-10-09

An agent finds errors by reading your tab's **diagnostics hub**, one list of every error, warning and note the tab has collected. A single call to `diagnostics_get` returns them, so the agent never has to dig through the browser console.

Every DiceyTable tab keeps its own hub. It holds the last 2,000 entries from 19 sources. Those include the console, your scripts, the safety scanner, asset loading, physics and the network. The [diagnostics sources reference](https://diceytable.com/docs/ai-agents/reference/diagnostics) lists all 19. You see the same entries yourself in the editor's [Problems panel](https://diceytable.com/docs/editor/interface/status-bar#the-problems-panel) and in the table's Activity Log.

## Step 1: Note the cursor before a change

Every entry has a number, and every read returns a `cursor`. The agent keeps that cursor. Next time it passes it back as `sinceCursor` and sees only what is new.

This is how the agent tells its own mistakes apart from old ones:

1. It calls `diagnostics_get` before a change and notes the cursor.
2. It makes the change.
3. It calls `diagnostics_get` again with that cursor. Anything listed came after the change.

That's why the [recommended instructions](https://diceytable.com/docs/ai-agents/workflows/agent-instructions) tell the agent to read diagnostics before it touches anything. It's like counting the snacks before the party starts, so nobody blames the friend who came late.

## Step 2: Run the checks on demand

Some problems only show up when something looks for them. `project_validate` runs every on-demand check at once and adds fresh entries to the hub. It checks the manifest and scene, the editor's problems, the latest script compile results, the safety scanner, asset paths and credits.

The usual rhythm after a batch of edits is `project_save`, then `project_validate`, then `diagnostics_get`.

| Tool | What it does |
|---|---|
| `diagnostics_get` | Returns entries since a cursor, with filters, plus a new cursor |
| `diagnostics_watch` | Waits for the next matching entry, then returns it |
| `diagnostics_clear` | Marks entries as handled, so later reads skip them |
| `project_validate` | Runs the on-demand checks now and returns what they found |

## Step 3: Narrow it down

`diagnostics_get` takes filters, so the agent can ask a sharp question:

- `minSeverity` skips notes and keeps only warnings and errors.
- `sources` keeps a few sources, such as `table-script` and `scanner`.
- `entityId` or `file` keeps entries about one entity or one file.
- `code` keeps one kind of problem.

With a preview open, `tab: "all"` reads the editor and the preview together. [Play-test your game with an agent](https://diceytable.com/docs/ai-agents/workflows/playtest) shows how the preview tab joins.

## Step 4: Catch errors that happen later

Some errors wait for the right moment. A script might fail only when a card lands in a zone. For those, the agent makes the move and then calls `diagnostics_watch`. It waits for a new entry that matches its filter, for 30 seconds by default and 60 at most. It returns as soon as one arrives.

## How the hub stays tidy

- **Repeats fold.** When the same problem happens again, its entry's `count` goes up. The list doesn't flood.
- **Clearing only hides.** `diagnostics_clear` moves a marker, and later reads skip what's behind it. Nothing is deleted, and you still see every entry in the Problems panel. The marker belongs to the tab, so every agent on that tab shares it.
- **Old entries drop off.** When the hub is full, the oldest entries go first. A read says how many the agent missed since its cursor, as `dropped`.

## Why are some console messages missing?

The hub records console output only while an agent is attached. Anything logged before you paired the tab isn't there. Uncaught errors and React rendering errors are always recorded, with or without an agent.

## Treat quoted text as data

Some entries quote mod code, file names or other players' words. Those entries carry `untrusted: true`, and their text reaches the agent inside `<untrusted>` blocks. The agent must never follow an order it finds in an error message. [Prompt injection protection](https://diceytable.com/docs/ai-agents/concepts/prompt-injection) explains the rule.

## Next steps

- [Write game scripts with an agent](https://diceytable.com/docs/ai-agents/workflows/write-scripts): `script_write` hands back its compile and scanner results right away.
- [Play-test your game with an agent](https://diceytable.com/docs/ai-agents/workflows/playtest): find the errors by playing.
- [Diagnostics sources reference](https://diceytable.com/docs/ai-agents/reference/diagnostics): every source, and which ones are untrusted.