# Diagnostics

Every code gpu-engine reports, with why it happens and how to fix it. Generated from the diagnostic registry in the library. `gpu-engine doctor` prints the same why and fix under each finding. Messages name files and counts, never examples.

## Definition, thrown by `defineModel` and `defineEval`

### DEFINE_NET_ORDER

Why: `net` must start with exactly one `embed` layer, and `embed` may not appear anywhere else.

Fix: Put one `layers.embed(size)` first in `net` and remove any other `embed` layer.

### DEFINE_LAYER_SHAPE

Why: A layer has a size, tap count or activation it cannot run with.

Fix: Use positive integer sizes, an odd `taps` of at least 1, and an activation from `relu`, `tanh` or `none`.

### DEFINE_FEATURE_ROW

Why: The token input cannot be featurized: `max` or `buckets` is not a positive integer, `k` is outside 1 to `buckets`, `rows` is empty or has an unknown kind, a flag name is empty, or a shape row or a flag name repeats.

Fix: Give `features.tokens` a positive integer `max` and at least one row, keep `k` between 1 and `buckets`, use one `features.shape()` and distinct non-empty flag names.

### DEFINE_HEAD_LABELS

Why: The head cannot be built from its labels: fewer than two labels, a duplicate label, or both or neither of `labels` and `outputs`.

Fix: Give the head two or more distinct `labels`, or for a pooled values head only `outputs`.

### DEFINE_BUDGET_EXCEEDED

Why: The layers already exceed a budget before any training: multiply-adds per token, or a packed int6 size that cannot fit the Brotli budget.

Fix: Shrink a layer (embed size, scan size, dense size, hash buckets) or raise the budget in `budgets`.

### DEFINE_SET_FOLDER

Why: Each set must live in its own folder: train in `data/train/`, dev in `data/dev/`, test in `data/test/`.

Fix: Move the files and point `sets` at `data/train/*.jsonl`, `data/dev/*.jsonl` and `sealed('data/test/*.jsonl')`.

## Weights file

### WEIGHTS_FORMAT_INVALID

Why: The bytes are not a gpu-engine weights file: the magic, a length or a tensor record is wrong.

Fix: Load the `weights/<name>.bin` file written by `gpu-engine promote`, or re-export it with the byte layout in SPEC section 5.

### WEIGHTS_VERSION_UNSUPPORTED

Why: The weights file uses a format version this runtime does not read.

Fix: Upgrade gpu-engine, or re-export the weights with the format version this runtime reads.

### WEIGHTS_DEFINITION_MISMATCH

Why: The definition hash or a tensor shape in the file does not match the definition the file carries.

Fix: Re-export the weights from the same definition, or run `gpu-engine promote` again to write a fresh file.

## Runtime, returned by `run`

### RUN_BACKEND_UNAVAILABLE

Why: The requested backend cannot run here: WebGPU is missing or no adapter was found.

Fix: Use `backend: 'auto'` or `'cpu'`, or pass a WebGPU entry point as `gpu` (in Node, the `webgpu` package).

### RUN_GPU_FAILED

Why: The GPU device was lost or reported a validation error while running the model.

Fix: Retry with `backend: 'cpu'`, and run `gpu-engine parity` to check the WGSL output.

### RUN_INPUT_INVALID

Why: The input is not a string or a `{ text, flags }` object, or a flag list does not have one entry per token.

Fix: Pass a string, or `{ text, flags }` where each flag array has one boolean per token of `text`.

### RUN_FAILED

Why: The model loaded, but running it failed for a reason no other run code covers, such as an op that throws.

Fix: Run `gpu-engine inspect "<text>"` on the same input to see which step fails, and report it with the weights file.

### RUN_TABLE_MISSING

Why: A retrieve model needs a table of rows to score the input against.

Fix: Pass `table` to `loadModel`: the `{ id, text }` rows the model ranks.

## Loading a model package

### PROJECT_FILE_MISSING

Why: The folder has no `*.model.ts` or no `*.eval.ts` file.

Fix: Run the command in the model package folder, pass `--dir <path>`, or create the file with `gpu-engine new`.

### PROJECT_FILE_AMBIGUOUS

Why: The folder has more than one `*.model.ts` or more than one `*.eval.ts` file.

Fix: Keep one model file and one eval file per package, or pass `--dir` to the package you mean.

### PROJECT_EXPORT_INVALID

Why: The model or eval file does not default-export the result of `defineModel` or `defineEval`.

Fix: Write `export default defineModel({ ... })` in the model file and `export default defineEval({ ... })` in the eval file.

## Data and the sealed test set

### DATA_SET_MISSING

Why: One of the train, dev or test sets has no files.

Fix: Add JSONL files to the set folder, or declare a generator in `defineDataset` and run `gpu-engine loop` to write them.

### DATA_SET_TOO_SMALL

Why: A set has fewer examples than `minSize` asks for.

Fix: Add examples or raise the generator count. Lower `minSize` only when the smaller set still measures the model.

### DATA_SPLIT_OVERLAP

Why: The same example, after normalising case and whitespace, appears in two sets, so a score there measures memory.

Fix: Remove the shared examples from one of the sets. Change the test set only by hand, then delete its lock entry and rerun.

### DATA_GROUP_SHARED

Why: A declared group appears in more than one set, so the split does not test anything new.

Fix: Move every example of the group into one set.

### DATA_VOCAB_SHARED

Why: A declared vocabulary word appears in more than one set, so the model can pass by memorising words.

Fix: Split the vocabulary so each word belongs to one set, or drop the word from the `vocab` field of those rows when sharing it is intended.

### DATA_HASH_CHANGED

Why: A data file no longer matches the hash recorded in `data.lock.json`.

Fix: Restore the file. If the change is intended, delete that set from `data.lock.json` by hand and rerun to record the new hash.

### DATA_TEST_READ

Why: Something other than `promote` read or referenced the sealed test set.

Fix: Remove the reference. Only the `sealed('data/test/...')` call in the eval file may name the test folder, and only `gpu-engine promote` reads it.

### DATA_TEST_PRINTED

Why: A test example or a test-only field was about to be printed or written to a file.

Fix: Report test results as per-set aggregates only. Tries rows hold dev scores only.

### DATA_ROW_INVALID

Why: A data row is not valid JSON or does not have the `{ input, gold }` shape the head needs.

Fix: Write one JSON object per line with `input` (text or `{ text, flags }`) and `gold` in the shape of the head.

### DATA_LABEL_UNKNOWN

Why: A gold label is not one of the head labels.

Fix: Fix the label in the data, or add it to the head `labels` in the model file.

## Budgets

### BUDGET_BYTES_EXCEEDED

Why: The Brotli-compressed weights are larger than `budgets.brotliBytes`.

Fix: Shrink the model (hash buckets, layer sizes) or raise the budget.

## Gate

### GATE_FLOOR_FAILED

Why: A set scored below the last promoted score minus the gate noise.

Fix: Keep tuning on dev with `gpu-engine loop` until every set is back above its floor.

### GATE_FILE_INVALID

Why: `gate.json` is not `{ level, promoted }` with `promoted` null or a promoted entry with dev and test scores.

Fix: Restore `gate.json` from history. Only `gpu-engine promote` and `promote --seal` write it.

## Promote

### PROMOTE_CANDIDATE_MISSING

Why: There is no candidate to promote.

Fix: Run `gpu-engine loop` first. It writes the candidate that `promote` scores.

### PROMOTE_CANDIDATE_STALE

Why: The model definition or the data changed after the candidate was trained.

Fix: Run `gpu-engine loop` to train a fresh candidate, then promote.

### PROMOTE_SCORE_FAILED

Why: `metric`, `decode` or a baseline threw while `promote` scored a test set. Its message is not shown, since it can quote a test example.

Fix: Make `metric`, `decode` and the baselines return a value for every input and gold the head can produce, check them on dev with `gpu-engine loop --fail`, then promote again.

### PROMOTE_OUTSIDE_CI

Why: The test set is sealed at level 3, so `promote` only runs in CI.

Fix: Run the `promote` workflow in CI. It holds the key in the `GPU_ENGINE_TEST_KEY` secret.

## Level 3 sealing

### SEAL_KEY_MISSING

Why: The test set is encrypted and no key was given.

Fix: Set `GPU_ENGINE_TEST_KEY` in the CI secret store. The key never goes into the repository.

### SEAL_KEY_INVALID

Why: The key is not 64 hex characters, or it does not decrypt the sealed test set.

Fix: Set `GPU_ENGINE_TEST_KEY` to the key written by `gpu-engine promote --seal`.

### SEAL_REFUSED

Why: `promote --seal` cannot seal this package: it is already at level 3, a sealed file or `.github/workflows/promote.yml` already exists, or the key path is inside the working tree or names a file that exists.

Fix: Seal once per package. Pass `--key-out` with a new file outside the repository, and move an existing promote workflow aside first.

### SEAL_PLAINTEXT_FOUND

Why: The package is sealed at level 3, but a plaintext test file is in the test folder, where any agent can read it.

Fix: Delete the plaintext file. The sealed `.enc` file beside it holds the test set, and only the promote workflow in CI decrypts it.

### SEAL_LOCK_INVALID

Why: The test entry of `data.lock.json` does not describe the sealed files: it is missing, names a file that is not sealed, or lacks a `plaintext` hash. A sealed set cannot be fingerprinted again without the key.

Fix: Restore `data.lock.json` and the `.enc` files from the commit that sealed them.

### SEAL_WORKFLOW_MISSING

Why: The package is sealed at level 3, but `.github/workflows/promote.yml` is missing or does not run `gpu-engine promote` with `GPU_ENGINE_TEST_KEY`, so nothing can promote it.

Fix: Restore `.github/workflows/promote.yml` from the commit that sealed the test set.

## `promote --verify`

### VERIFY_SCORE_CHANGED

Why: Re-scoring the committed weights on dev does not give the scores in `report.json`.

Fix: Run `gpu-engine promote` again to write a report for these weights. Never edit `report.json` by hand.

### VERIFY_WEIGHTS_CHANGED

Why: The committed weights do not match the hash in `report.json`.

Fix: Restore the promoted weights, or run `gpu-engine promote` again.

### VERIFY_FILE_STALE

Why: A generated file (`MODEL_CARD.md`, `RESULTS.md`, `src/weights.ts`) does not match what the report regenerates.

Fix: Run `gpu-engine promote` again. Never edit generated files by hand.

### VERIFY_READS_MISSING

Why: `reads.jsonl` has fewer test reads than the report counts.

Fix: Restore `reads.jsonl` from history. The read log is append-only.

### VERIFY_REPORT_INVALID

Why: `report.json` is missing or is not the report `gpu-engine promote` writes.

Fix: Run `gpu-engine promote` to write it, or restore it from history. Never edit `report.json` by hand.

## Parity

### PARITY_ADAPTER_MISSING

Why: No WebGPU adapter was found, so the WGSL output cannot be compared.

Fix: Install the `webgpu` package and a Vulkan driver (on Linux, `apt-get install mesa-vulkan-drivers` for lavapipe).

### PARITY_DECODE_DIFFERS

Why: The WGSL and CPU outputs decode to different results on a fixture.

Fix: Find the layer that diverges with the layer tests in `test/gpu`, and fix its WGSL template.

### PARITY_TOLERANCE_EXCEEDED

Why: The largest logit difference between WGSL and CPU is above `parity.tolerance`.

Fix: Fix the diverging WGSL template. Raise `parity.tolerance` only with a measured reason.

## Ship checks

### SHIP_SIZE_EXCEEDED

Why: The built model package, with its weights, is larger than `ship.brotliBytes` after Brotli.

Fix: Shrink the model or the decode code, or raise `ship.brotliBytes`.

### SHIP_PACKAGE_INVALID

Why: The ship checks read what the package ships from `package.json` and `npm pack --dry-run --json`, and one of them is missing, does not parse or failed.

Fix: Run doctor in the model package folder, fix `package.json` until `npm pack --dry-run` lists its files, and check that `npm` is on the PATH.

### SHIP_DEPENDENCY_FOUND

Why: The model package declares a runtime dependency (`dependencies`, `peerDependencies`, `optionalDependencies` or `bundleDependencies`), or a shipped script imports another module. The shipped model must have zero runtime dependencies.

Fix: Move the package to `devDependencies` and bundle what the model needs into the build with `npm run build`.

### SHIP_BUILD_STALE

Why: The package has promoted weights, but no packed file holds them, so the build predates the promotion and the size check would measure a model without its weights.

Fix: Run `npm run build` after `gpu-engine promote`, then run doctor again.

### SHIP_FILE_NOT_ALLOWED

Why: The packed model package contains a file outside `ship.files`.

Fix: Add the file to `files` in package.json only if it must ship, and list it in `ship.files`; otherwise exclude it.

## NEW

### NEW_NAME_INVALID

Why: The model name becomes the package name, the file names and the weights file name, so it must be a lowercase npm package name without a scope.

Fix: Use lowercase letters, digits and `-`, starting with a letter, at most 64 characters, such as `unit-phrases`.

### NEW_TARGET_EXISTS

Why: `gpu-engine new` writes a fresh package and never overwrites a file, and the target folder already holds files.

Fix: Pick another name, pass `--dir` to create the package somewhere else, or remove the folder first.

## Command line

### CLI_COMMAND_UNKNOWN

Why: The command is not one of `new`, `loop`, `promote`, `parity`, `inspect` or `doctor`.

Fix: Run `gpu-engine --help` to see the commands.

### CLI_FLAG_INVALID

Why: A flag is unknown for this command, is missing its value, or a required argument is missing.

Fix: Run `gpu-engine <command> --help` to see its arguments and flags.

<!-- vitehub-docs:section-links -->
## In this section

- [Layer catalog](https://gpu-engine.dev/raw/docs/reference/layers.md)
- [CLI](https://gpu-engine.dev/raw/docs/reference/cli.md)
- [Diagnostics](https://gpu-engine.dev/raw/docs/reference/diagnostics.md) (this page)

All pages: [llms.txt](https://gpu-engine.dev/llms.txt)
