Skip to content
Skills Library
Programming · Analysis

indexing-errors

/indexing-errors

List every `boxel_index` row in a realm whose latest indexing attempt failed (`has_error = TRUE`), rendered cleanly but holds broken `linksTo` / `linksToMany` targets, indexed but couldn't parse its frontmatter YAML, or indexed a skill whose frontmatter tools failed schema generation. Use to answer "why is this realm broken", "what's failing to index", "which cards have dead references", "why did my skill's commands disappear", or "why isn't my skill's tool callable" without reading the database directly.

Repository
boxel ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

84/ 100Class: good
Format9 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
2
URLs in SKILL.md
23
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

List every `boxel_index` row in a realm whose latest indexing attempt failed (`has_error = TRUE`), rendered cleanly but holds broken `linksTo` / `linksToMany` targets, indexed but couldn't parse its frontmatter YAML, or indexed a skill whose frontmatter tools failed schema generation. Use to answer "why is this realm broken", "what's failing to index", "which cards have dead references", "why did my skill's commands disappear", or "why isn't my skill's tool callable" without reading the database directly.

Triggers from the description

why is this realm brokenwhatwhich cards have dead referenceswhy did my skill, ort my skill
Original author description

List every `boxel_index` row in a realm whose latest indexing attempt failed (`has_error = TRUE`), rendered cleanly but holds broken `linksTo` / `linksToMany` targets, indexed but couldn't parse its frontmatter YAML, or indexed a skill whose frontmatter tools failed schema generation. Use to answer "why is this realm broken", "what's failing to index", "which cards have dead references", "why did my skill's commands disappear", or "why isn't my skill's tool callable" without reading the database directly.

How it works

  1. When the user asks to...
  2. Typical sequencing
  3. Commands
  4. Output shape
  5. Pitfalls
Original SKILL.md headings · 168 lines, 1,125 words
SKILL.md preview
---
description: List every `boxel_index` row in a realm whose latest indexing attempt failed (`has_error = TRUE`), rendered cleanly but holds broken `linksTo` / `linksToMany` targets, indexed but couldn't parse its frontmatter YAML, or indexed a skill whose frontmatter tools failed schema generation. Use to answer "why is this realm broken", "what's failing to index", "which cards have dead references", "why did my skill's commands disappear", or "why isn't my skill's tool callable" without reading the database directly.
---

# Realm indexing errors

`boxel realm indexing-errors` returns four classes of "indexing finding" for a realm:

1. **`indexing-error`** — `boxel_index` rows where `has_error = TRUE`. The render or file extract failed and the persisted `errorDoc` (a `SerializedError`: `message`, `status`, `title`, optional `stack`, optional `deps`) explains why.
2. **`broken-link`** — `boxel_index` rows where `has_error = FALSE` but the indexer's `render.meta` scan persisted a non-empty `diagnostics.brokenLinks` array. The card itself indexes fine; one or more `linksTo` / `linksToMany` targets are dead. Each entry exposes `attributes.brokenLinks: BrokenLinkSummary[]` — `{ fieldName, reference, kind: 'error' | 'not-found' }`.
3. **`frontmatter-error`** — `boxel_index` rows where `has_error = FALSE` but a markdown file's leading YAML frontmatter wouldn't parse, persisted as `diagnostics.frontmatterParseError`. The file indexes body-only, so anything the frontmatter declared (a skill's `commands`, its `boxel.kind`, etc.) was silently dropped — this finding is the only signal the author gets. Each entry exposes `attributes.frontmatterParseError` — `{ message, line?, column? }`.
4. **`tool-schema-error`** — `boxel_index` rows where `has_error = FALSE` but one or more of a skill markdown file's frontmatter tools failed index-time schema generation (module wouldn't load, missing export, schema generation threw), persisted as `diagnostics.toolSchemaErrors`. The skill indexes with the tools that did enrich; each failed tool won't be callable via the pull model until fixed — this finding is the only indexed signal. Each entry exposes `attributes.toolSchemaErrors: ToolSchemaError[]` — `{ module, name, message }`.

Use this skill to triage realm health in one call, without reading the database directly or scraping per-card failures.

## When the user asks to...

| Ask                                                                          | Run                                                                                                              |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| "what's failing to index in <realm>?"                                        | `boxel realm indexing-errors --realm <realm-url>`                                                                |
| "which cards have broken links in <realm>?"                                  | `boxel realm indexing-errors --realm <realm-url> --json \| jq '.data[] \| select(.type == "broken-link")'`       |
| "why did my skill's commands disappear / which files have bad frontmatter?"  | `boxel realm indexing-errors --realm <realm-url> --json \| jq '.data[] \| select(.type == "frontmatter-error")'` |
| "why isn't my skill's tool callable / which tools failed schema generation?" | `boxel realm indexing-errors --realm <realm-url> --json \| jq '.data[] \| select(.type == "tool-schema-error")'` |
| "give me the full payload as JSON"                                           | `boxel realm indexing-errors --realm <realm-url> --json`                                                         |
| "is anything broken in this realm right now?"                                | `boxel realm indexing-errors --realm <realm-url>` — exit 0 with "No indexing errors." is the all-clear           |

## Typical sequencing

Default triage loop after a sync or a suspected break:

```bash
boxel realm wait-for-ready --realm https://app.boxel.ai/owner/realm/
boxel realm indexing-errors --realm https://app.boxel.ai/owner/realm/
# if findings appear, fetch the offender's source and dependencies:
boxel file read https://app.boxel.ai/owner/realm/ <path-from-url>
boxel realm indexing-errors --realm https://app.boxel.ai/owner/realm/ --json \
  | jq '.data[] | {type, url: .attributes.url, msg: (.attributes.errorDoc.message // (.attributes.brokenLinks | length | tostring + " broken"))}'
```

Each finding reflects that URL's **most recent** indexing attempt. The `boxel_index` primary key is `(url, realm_url, type)` — a successful re-index of the same `(url, type)` overwrites the row in place. A single URL can produce multiple findings if both its `instance` and `file` rows are affected; the JSON-API resource `id` is `${entryType}::${url}` so each finding is unique.

<!-- generated:commands:start -->

## Commands

_Generated from the boxel-cli Commander tree by_ `pnpm build:plugin`. _Edit prose outside the generated block — never inside it._

### `boxel realm indexing-errors`

List every card or module in a realm whose latest indexing attempt errored

**Options:**

- `--realm <realm-url>` — The realm URL to query
- `--json` — Output the full JSON-API document

<!-- generated:commands:end -->

## Output shape

Default (human-readable):

```
4 indexing findings for https://realm.example.com/:
[instance] https://realm.example.com/broken-card.json  Cannot find module './missing'
[file]     https://realm.example.com/recipes.gts        Unexpected token '<'
[instance] https://realm.example.com/clean-but-linked.json  2 broken: author→https://…, tags→https://…
[file]     https://realm.example.com/skills/sync/SKILL.md  frontmatter parse error (line 4:3): Implicit map keys need to be on a single line
```

Each line is `[<entryType>] <url>  <short summary>`. For `indexing-error` rows the summary is `errorDoc.title` (falling back to `errorDoc.message`). For `broken-link` rows it is `<N> broken: fieldName→reference, …` (up to three, then `+N more`). For `frontmatter-error` rows it is `frontmatter parse error (line L:C): <message>`. For `tool-schema-error` rows it is `<N> tool schema failure(s): module#name: <message>; …` (up to three, then `+N more`).

`--json` emits a JSON-API document:

```json
{
  "data": [
    {
      "type": "indexing-error",
      "id": "instance::https://realm.example.com/broken-card.json",
      "attributes": {
        "url": "https://realm.example.com/broken-card.json",
        "entryType": "instance",
        "errorDoc": { "message": "...", "status": 500, "title": "..." },
        "diagnostics": { "invalidationId": "...", "renderMs": 42 }
      }
    },
    {
      "type": "broken-link",
      "id": "instance::https://realm.example.com/clean-but-linked.json",
      "attributes": {
        "url": "https://realm.example.com/clean-but-linked.json",
        "entryType": "instance",
        "diagnostics": {
          "brokenLinks": [
            {
              "fieldName": "author",
              "reference": "https://...",
              "kind": "not-found"
            }
          ]
        },
        "brokenLinks": [
          {
            "fieldName": "author",
            "reference": "https://...",
            "kind": "not-found"
          }
        ]
      }
    },
    {
      "type": "frontmatter-error",
      "id": "file::https://realm.example.com/skills/sync/SKILL.md",
      "attributes": {
        "url": "https://realm.example.com/skills/sync/SKILL.md",
        "entryType": "file",
        "diagnostics": {
          "frontmatterParseError": {
            "message": "Implicit map keys need to be on a single line",
            "line": 4,
            "column": 3
          }
        },
        "frontmatterParseError": {
          "message": "Implicit map keys need to be on a single line",
          "line": 4,
          "column": 3
        }
      }
    },
    {
      "type": "tool-schema-error",
      "id": "file::https://realm.example.com/skills/sync/SKILL.md",
      "attributes": {
        "url": "https://realm.example.com/skills/sync/SKILL.md",
        "entryType": "file",
        "diagnostics": {
          "toolSchemaErrors": [
            {
              "module": "https://realm.example.com/missing-tool",
              "name": "default",
              "message": "Could not find module"
            }
          ]
        },
        "toolSchemaErrors": [
          {
            "module": "https://realm.example.com/missing-tool",
            "name": "default",
            "message": "Could not find module"
          }
        ]
      }
    }
  ]
}
```

## Pitfalls

- `--realm` is required and must be the realm base URL (with the realm path, not just the server origin).
- The endpoint reports findings for **all** entry types (instances, modules, files) — not just card instances. A failing `.gts` shows up here even if it isn't published as a card.
- The default human-readable line truncates the error message to 100 characters and prefers `errorDoc.title` over `errorDoc.message`. Use `--json` for the full payload.
- `broken-link`, `frontmatter-error`, and `tool-schema-error` findings have **no** `errorDoc` — `has_error` is `FALSE`. Branch on `data[].type` (or check `attributes.brokenLinks` / `attributes.frontmatterParseError` / `attributes.toolSchemaErrors`) before reading `errorDoc`.
- A `frontmatter-error` means the file _did_ index — just without its frontmatter. The body is fine; whatever the YAML declared (skill `commands`, `boxel.kind`) is gone until the YAML is fixed and the realm re-indexes.
- A `tool-schema-error` likewise means the skill _did_ index; only the named tools lack generated schemas. Fixing the tool module (or the codeRef) and re-indexing the skill file clears it.
- JSON-API resource `id` is `${entryType}::${url}`, not bare `${url}`. To get the URL back, read `attributes.url`.
- On transport failure with `--json`, stdout receives `{"error":"..."}` (not the data envelope) and the process exits non-zero. Successful calls always emit `{ "data": [...] }`. A consumer reading only stdout can distinguish failure from "realm is healthy" by checking for the `error` key (or the exit code).
- The list does not include queue depth, running-job progress, or a "last finished at" timestamp. Those are separate concerns and may be folded into a future `indexing-status` command.

Versions

The database has no other skills named indexing-errors.

Database snapshot: 13.11.2026 · package version f7395d4b6efa (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 84realm-history
    Local checkpoint history plus realm-indexing control. Use when the user wants to view / restore / create checkpoints in `.boxel-history/`, wait for a realm to finish indexing, or cancel a running indexing job.
  • 100realm-server-test-setup
    How to set up realms in a packages/realm-server test module without indexing them from scratch before every test — which helper to use (setupPermissionedRealmCached, setupPermissionedRealmsCached, setupTestDatabaseTemplate), when a test genuinely needs a fresh boot index, and…
  • 100cursor-indexing-issues
    Manage troubleshoot Cursor codebase indexing problems. Triggers on "cursor indexing", "cursor index", "cursor codebase", "@codebase not working", "cursor search broken". Use when working with cursor indexing issues functionality. Trigger with phrases like "cursor indexing…
  • 100orchardcore-indexing
    Skill for the Orchard Core indexing infrastructure. Covers how content items reach an index (immediate deferred indexing and the task log processed by the Indexing Worker), content part, field and document index handler contracts, DocumentIndex value types and…
  • 100cursor-indexing-issues
    Troubleshoot Cursor codebase indexing: stuck indexing, empty search, @codebase failures, and performance issues. Triggers on "cursor indexing", "cursor index", "@codebase not working", "cursor search broken", "indexing stuck".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.