Przejdź do treści
Biblioteka skilli
Programowanie · Analiza

indexing-errors

/indexing-errors

Wypisuje wiersze indeksu boxel, których ostatnia próba indeksowania się nie powiodła, z martwymi odnośnikami lub błędnym YAML.

Repozytorium
boxel ↗
Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

84/ 100Klasa: dobry
Format9 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
2
Adresy URL w SKILL.md
23
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

Co robi i kiedy

Wypisuje wiersze indeksu boxel, których ostatnia próba indeksowania się nie powiodła, z martwymi odnośnikami lub błędnym YAML.

Wyzwalacze z opisu

why is this realm brokenwhatwhich cards have dead referenceswhy did my skill, ort my skill
Oryginalny opis (EN)

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.

Jak działa

  1. When the user asks to...
  2. Typical sequencing
  3. Commands
  4. Output shape
  5. Pitfalls
Sekcje z nagłówków SKILL.md, w oryginale · 168 linii, 1 125 słów
Podgląd SKILL.md
---
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.

Wersje

W bazie nie ma innych skilli o nazwie indexing-errors.

Migawka bazy z 13.11.2026 · wersja paczki f7395d4b6efa (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 84realm-history
    Zarządza lokalnymi punktami kontrolnymi realmu Boxel i czeka na zakończenie indeksowania albo je anuluje.
  • 100realm-server-test-setup
    Ustawia realmy w testach packages/realm-server bez indeksowania od zera przed każdym testem, dobierając helper i szablon bazy danych.
  • 100cursor-indexing-issues
    Rozwiązuje problemy z indeksowaniem kodu w Cursor, gdy @codebase nie działa lub wyszukiwanie jest zepsute.
  • 100orchardcore-indexing
    Opisuje infrastrukturę indeksowania Orchard Core: indeksowanie natychmiastowe i odroczone, dziennik zadań przetwarzany przez Indexing Worker oraz handlery indeksu części, pól i dokumentów.
  • 100cursor-indexing-issues
    Rozwiązuje problemy z indeksowaniem kodu w Cursor: zawieszone indeksowanie, puste wyszukiwanie, błędy @codebase i wydajność.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.