Specification

Error code registry

Every refusal and every Runtime API failure in IDOP carries one of these 169 stable codes (§16). Codes are only ever added; a published code keeps its meaning forever.

Machine-readable: error-codes.json. The meanings below are diagnostic text for implementers; a Reader explains each code to the user in the user's own language, but never translates the code itself.

Prefixes: IDOP-BUNDLE · IDOP-CREDENTIAL · IDOP-ENV · IDOP-HOST · IDOP-ITEMS · IDOP-LIMIT · IDOP-MANIFEST · IDOP-NETWORK · IDOP-PATH · IDOP-POLICY · IDOP-PROFILE · IDOP-PROJECT · IDOP-RUNTIME · IDOP-SAVE · IDOP-STORAGE · IDOP-THUMB · IDOP-UI · IDOP-UNSUPPORTED · IDOP-WS · IDOP-ZIP

`IDOP-BUNDLE-*`

Code	Meaning	Section
`IDOP-BUNDLE-ENTRY-001`	The bundle does not carry the entry that was asked for.	§14, Containers
`IDOP-BUNDLE-INPUT-001`	The declared entry lengths do not match the bundle payload.	§14, Containers
`IDOP-BUNDLE-INTEGRITY-001`	The manifest names a file the bundle does not carry. It is incomplete or was edited after packing.	§14, Containers
`IDOP-BUNDLE-INTEGRITY-002`	A file in this bundle does not match the digest its manifest recorded. It was corrupted or altered.	§14, Containers
`IDOP-BUNDLE-INTEGRITY-003`	The bundle manifest lists the same entry twice.	§14, Containers
`IDOP-BUNDLE-INTEGRITY-004`	This bundle carries a file its manifest does not declare. An undeclared extra file is refused, not imported.	§14, Containers
`IDOP-BUNDLE-LIMIT-001`	This bundle exceeds the total size the Reader will expand.	§14, Containers
`IDOP-BUNDLE-LIMIT-002`	This bundle contains more entries than the Reader will accept.	§14, Containers
`IDOP-BUNDLE-LIMIT-003`	One entry in this bundle exceeds the per-file size limit.	§14, Containers
`IDOP-BUNDLE-MANIFEST-001`	The bundle manifest is not valid JSON, or is too large.	§14, Containers
`IDOP-BUNDLE-MANIFEST-002`	The bundle manifest does not match the schema: a field is missing, unknown, or the wrong shape.	§14, Containers
`IDOP-BUNDLE-MANIFEST-003`	The bundle manifest is the right shape but the wrong contents.	§14, Containers
`IDOP-BUNDLE-MANIFEST-004`	The bundle name is empty or longer than 120 characters.	§14, Containers
`IDOP-BUNDLE-MANIFEST-005`	The bundle manifest could not be serialised.	§14, Containers
`IDOP-BUNDLE-PATH-001`	This bundle carries an entry outside its `content/` directory. A bundle transports a directory and nothing else.	§14, Containers
`IDOP-BUNDLE-PATH-002`	This bundle carries a path the Reader refuses: it escapes the directory, is absolute, or uses a name a filesystem would read differently.	§14, Containers
`IDOP-BUNDLE-PATH-003`	This bundle contains another bundle. One import expands exactly one level.	§14, Containers
`IDOP-BUNDLE-PROFILE-001`	This file has no `idop.bundle.json`, so nothing describes what it is meant to carry.	§14, Containers
`IDOP-BUNDLE-SCHEMA`	The bundle manifest does not validate against the bundle schema.	§14, Containers
`IDOP-BUNDLE-SCOPE-001`	A bundle scope must be workspace, folder or project.	§14, Containers
`IDOP-BUNDLE-UNSUPPORTED-001`	This bundle declares a format or version this Reader does not implement.	§14, Containers

`IDOP-CREDENTIAL-*`

Code	Meaning	Section
`IDOP-CREDENTIAL-MISSING`	The document needs a credential that is not configured in this Reader.	§12.2
`IDOP-CREDENTIAL-ORIGIN-DENIED`	The document wants a Reader credential sent to an origin that does not belong to that provider. The Reader refuses, whatever the manifest declares.	§12.2

`IDOP-ENV-*`

Code	Meaning	Section
`IDOP-ENV-DENIED`	The document asked for an environment binding it never declared.	§12.3
`IDOP-ENV-MISSING`	The document needs an environment variable that is not set.	§12.3

`IDOP-HOST-*`

Code	Meaning	Section
`IDOP-HOST-NO-INPUT`	host.getInputFile() was called by a document that was not opened to display a file.	§11.4

`IDOP-ITEMS-*`

Code	Meaning	Section
`IDOP-ITEMS-CYCLE-001`	The item hierarchy contains a cycle, so no item has a root.	Containers §5
`IDOP-ITEMS-DECL-001`	This document’s Portable Items declaration does not match the contract.	Containers §5
`IDOP-ITEMS-DECL-002`	The Portable Items declaration is not well-formed JSON of the expected shape.	Containers §5
`IDOP-ITEMS-DECL-003`	A Portable Items path is not a valid storage path — it escapes storage, or is absolute.	Containers §5
`IDOP-ITEMS-DECL-004`	A shared dependency cannot live inside an item’s own state.	Containers §5
`IDOP-ITEMS-DECL-005`	The item index cannot live inside an item’s own state.	Containers §5
`IDOP-ITEMS-DEPENDENCY-001`	An item depends on something its manifest did not declare. An item cannot widen what it may carry.	Containers §5
`IDOP-ITEMS-DEPENDENCY-002`	An item depends on state the document does not carry.	Containers §5
`IDOP-ITEMS-DUPLICATE-001`	The item index lists the same item identifier twice.	Containers §5
`IDOP-ITEMS-INDEX-001`	The document declares an item index it has not written yet.	Containers §5
`IDOP-ITEMS-INDEX-002`	The Portable Items index is not valid JSON or exceeds its byte limit.	Containers §5
`IDOP-ITEMS-INDEX-003`	The item index does not match the contract’s schema.	Containers §5
`IDOP-ITEMS-INDEX-004`	The Portable Items index does not have the expected shape.	Containers §5
`IDOP-ITEMS-LIMIT-001`	This document exposes more items than the Reader will list.	Containers §5
`IDOP-ITEMS-LIMIT-002`	Exporting this item would exceed the size the Reader will derive.	Containers §5
`IDOP-ITEMS-NOT-FOUND-001`	That item is not in the document’s index.	Containers §5
`IDOP-ITEMS-PARENT-001`	An item names a parent that is not in the index.	Containers §5
`IDOP-ITEMS-PROFILE-001`	Portable Items needs the 0.2-draft profile. A 0.1 document has no way to maintain the index the contract requires.	Containers §5
`IDOP-ITEMS-UNSUPPORTED-001`	This document uses a Portable Items version the Reader does not implement.	Containers §5
`IDOP-ITEMS-UNSUPPORTED-002`	This document does not offer portable items.	Containers §5

`IDOP-LIMIT-*`

Code	Meaning	Section
`IDOP-LIMIT-001`	The file is larger than the Reader limit for a compressed package.	§6
`IDOP-LIMIT-002`	The package has more entries than the limit (§6).	§6
`IDOP-LIMIT-003`	A single entry exceeds the Reader limit.	§6
`IDOP-LIMIT-004`	An entry decompresses out of all proportion to its stored size. That is what a ZIP bomb looks like.	§6
`IDOP-LIMIT-005`	Decompressed, the package exceeds the total Reader limit.	§6
`IDOP-LIMIT-010`	idop.json is larger than the manifest size limit (§6).	§6
`IDOP-LIMIT-011`	idop.json is nested too deeply or has too many nodes (§6).	§6

`IDOP-MANIFEST-*`

Code	Meaning	Section
`IDOP-MANIFEST-001`	The manifest is not a valid JSON document.	§7, §12
`IDOP-MANIFEST-003`	idop.json does not validate against the manifest schema (Annex A): an unknown member, a missing member or an invalid value.	§7, §12
`IDOP-MANIFEST-004`	idop.json has the right shape for the schema but a value of the wrong type for this version.	§7, §12
`IDOP-MANIFEST-010`	The entry point must be an HTML file below `code/`.	§7, §12
`IDOP-MANIFEST-011`	application.id is not a lowercase reverse-domain identifier.	§7, §12
`IDOP-MANIFEST-012`	application.version is not a valid Semantic Versioning 2.0.0 version.	§7, §12
`IDOP-MANIFEST-013`	state.schemaVersion is not a valid Semantic Versioning 2.0.0 version.	§7, §12
`IDOP-MANIFEST-014`	The document's revision lineage or timestamps are inconsistent (§7.4).	§7, §12
`IDOP-MANIFEST-015`	A timestamp is not a valid RFC 3339 UTC timestamp.	§7, §12
`IDOP-MANIFEST-016`	A list in idop.json that must hold unique values contains duplicates.	§7, §12
`IDOP-MANIFEST-020`	The declared entry point does not exist in the package.	§7, §12
`IDOP-MANIFEST-021`	The declared icon must point at an existing entry in `resources/`.	§7, §12
`IDOP-MANIFEST-022`	Capability identifiers must be unique and of type `network`.	§7, §12
`IDOP-MANIFEST-023`	A network capability needs at least one exact HTTPS origin — no path, query or fragment — and at least one method.	§7, §12
`IDOP-MANIFEST-024`	A capability refers to a credential binding the manifest never declared.	§7, §12
`IDOP-MANIFEST-025`	A credential binding names a provider; in 1.x a binding names no service (§12.2). The 1.0 schema refuses the member first (IDOP-MANIFEST-003), so a 1.0 validator that applies §9.1 in order never raises this code.	§7, §12
`IDOP-MANIFEST-026`	A credential binding is not referenced by any capability (§12.2).	§7, §12
`IDOP-MANIFEST-027`	Environment binding identifiers must be unique (§12.3).	§7, §12
`IDOP-MANIFEST-028`	Credential binding identifiers must be unique (§12.2).	§7, §12

`IDOP-NETWORK-*`

Code	Meaning	Section
`IDOP-NETWORK-BUDGET-EXHAUSTED`	The document has used up the network requests allotted to this session.	§11.3, §12.5
`IDOP-NETWORK-CONCURRENCY`	The document has too many requests in flight at once.	§11.3, §12.5
`IDOP-NETWORK-DENIED`	The document asked for a capability it was not granted.	§11.3, §12.5
`IDOP-NETWORK-METHOD-DENIED`	The request uses a method the capability does not declare.	§11.3, §12.5
`IDOP-NETWORK-ORIGIN-DENIED`	The request target is not one of the origins the document declared and the user approved.	§11.3, §12.5
`IDOP-NETWORK-REQUEST-TOO-LARGE`	The request exceeds the Reader limit.	§11.3, §12.5
`IDOP-NETWORK-RESPONSE-TOO-LARGE`	The response exceeds the Reader limit.	§11.3, §12.5
`IDOP-NETWORK-TIMEOUT`	The provider did not answer within the allotted time.	§11.3, §12.5

`IDOP-PATH-*`

Code	Meaning	Section
`IDOP-PATH-001`	An entry name is empty or longer than 240 bytes (§5).	§4.3, §5
`IDOP-PATH-002`	Absolute, UNC and backslash paths are forbidden.	§4.3, §5
`IDOP-PATH-003`	An entry name contains NUL or a control character (§5).	§4.3, §5
`IDOP-PATH-004`	An entry name is not normalised to Unicode NFC (§5).	§4.3, §5
`IDOP-PATH-005`	An entry name has more than 16 segments (§5).	§4.3, §5
`IDOP-PATH-006`	A path tries to escape the package (`.` or `..`). That is the classic ZIP-slip attack.	§4.3, §5
`IDOP-PATH-007`	The name would be ambiguous on Windows (a trailing dot or space, or a colon).	§4.3, §5
`IDOP-PATH-008`	A reserved Windows device name was used (CON, PRN, AUX, NUL, COM1…).	§4.3, §5
`IDOP-PATH-009`	Paths carrying a drive letter are forbidden.	§4.3, §5
`IDOP-PATH-010`	Only these may appear at the package root: mimetype, idop.json, code/, resources/, storage/, _idop/ and extensions/.	§4.3, §5
`IDOP-PATH-011`	The archive contains a directory entry; packages contain files only.	§4.3, §5
`IDOP-PATH-012`	An entry under extensions/ lacks a reverse-domain namespace and a child path (§4.3).	§4.3, §5
`IDOP-PATH-020`	Bridge storage paths are relative to `storage/` and must not repeat that prefix.	§4.3, §5
`IDOP-PATH-030`	Two entries collide once Unicode and case are normalised. The Reader could not tell which one to run.	§4.3, §5
`IDOP-PATH-031`	Two entries have exactly the same name.	§4.3, §5
`IDOP-PATH-040`	A source directory being packed contains a symbolic link.	§4.3, §5

`IDOP-POLICY-*`

Code	Meaning	Section
`IDOP-POLICY-001`	Executable content is allowed only below `code/`.	§8
`IDOP-POLICY-002`	Below `code/` only HTML, JS/MJS, CSS, JSON and WebAssembly modules are allowed.	§8
`IDOP-POLICY-003`	An entry under code/ is not valid UTF-8 text (§8).	§8
`IDOP-POLICY-004`	A .wasm file under code/ is not a WebAssembly binary module.	§8, Executable boundary
`IDOP-POLICY-010`	The document code contains a forbidden primitive: `eval`, `new Function`, a shared or service worker, `window.open`, a `javascript:` URL or a native IPC symbol (§8, rule 5).	§8
`IDOP-POLICY-011`	The document HTML references a remote URL or an active embedding element. IDOP documents are fully offline.	§8
`IDOP-POLICY-012`	A stylesheet references a remote URL or uses `@import`.	§8
`IDOP-POLICY-013`	HTML under code/ contains an unterminated or inline script (§8).	§8
`IDOP-POLICY-014`	Inline scripts are forbidden; document code lives in its own files.	§8

`IDOP-PROFILE-*`

Code	Meaning	Section
`IDOP-PROFILE-001`	The first entry must be an uncompressed `mimetype` entry.	§4.2, §7.5
`IDOP-PROFILE-002`	The `mimetype` entry does not hold the exact IDOP media type.	§4.2, §7.5
`IDOP-PROFILE-003`	The `idop.json` manifest is missing.	§4.2, §7.5
`IDOP-PROFILE-004`	The package contains no `code/**`, so there is nothing to run.	§4.2, §7.5
`IDOP-PROFILE-005`	The mimetype entry and the manifest's formatVersion disagree (§7.5).	§4.2, §7.5

`IDOP-PROJECT-*`

Code	Meaning	Section
`IDOP-PROJECT-MANIFEST-001`	The project marker is not valid JSON, or is too large.	Containers
`IDOP-PROJECT-MANIFEST-002`	The project marker does not match the schema.	Containers
`IDOP-PROJECT-MANIFEST-003`	The project marker does not have the expected shape.	Containers
`IDOP-PROJECT-MEMBER-001`	A project member path escapes the project, or uses a name the Reader refuses.	Containers
`IDOP-PROJECT-MEMBER-002`	The project lists the same member twice.	Containers
`IDOP-PROJECT-MEMBER-003`	A project cannot contain a workspace or another project. It holds cooperating documents and their files.	Containers
`IDOP-PROJECT-MEMBER-004`	A project using explicit discovery must list its members.	Containers
`IDOP-PROJECT-SCHEMA`	The project marker does not validate against the project schema.	Containers

`IDOP-RUNTIME-*`

Code	Meaning	Section
`IDOP-RUNTIME-LIMIT`	A Runtime API request or response exceeds a Reader limit.	§11
`IDOP-RUNTIME-METHOD`	The document called a Runtime API method that does not exist.	§11
`IDOP-RUNTIME-SCHEMA`	A Runtime API call was made with parameters of the wrong shape.	§11
`IDOP-RUNTIME-UNAVAILABLE`	The Runtime API is not available (for example, the session has ended).	§11

`IDOP-SAVE-*`

Code	Meaning	Section
`IDOP-SAVE-CONFLICT`	The file changed on disk after it was opened. The Reader will not overwrite it — use “Save as”.	§10.3

`IDOP-STORAGE-*`

Code	Meaning	Section
`IDOP-STORAGE-ENCODING`	Binary data passed to the storage API is not canonical standard base64.	§11, Runtime API
`IDOP-STORAGE-NOT-FOUND`	storage.read named a path that does not exist in the overlay.	§10, §11
`IDOP-STORAGE-QUOTA`	The document has used up the storage space allotted to it.	§10, §11
`IDOP-STORAGE-UTF8`	storage.read named an entry that is not UTF-8 text; use storage.readBytes.	§10, §11

`IDOP-THUMB-*`

Code	Meaning	Section
`IDOP-THUMB-001`	_idop/thumbnail.png is present but is not an acceptable PNG (warning, never a refusal).	1.1 §3
`IDOP-THUMB-002`	A 1.0 package carries _idop/thumbnail.png, which 1.0 reserves (warning, never a refusal).	1.1 §3
`IDOP-THUMB-NOT-FOUND`	The package has no usable thumbnail.	1.1 §3

`IDOP-UI-*`

Code	Meaning	Section
`IDOP-UI-CANCELLED`	The user closed a Reader dialog (save, open) without choosing.	§11, Runtime API
`IDOP-UI-DENIED`	The Reader does not offer that dialog here, or the browser refused it (for example, no user gesture).	§11, Runtime API
`IDOP-UI-TOO-LARGE`	A file to save or open exceeds 16 MiB.	§11, Runtime API

`IDOP-UNSUPPORTED-*`

Code	Meaning	Section
`IDOP-UNSUPPORTED-001`	The package targets a format or Runtime API version this Reader does not implement.	§7.2, §15
`IDOP-UNSUPPORTED-002`	The package requires an unknown runtime feature. The Reader refuses rather than guessing.	§7.2, §15
`IDOP-UNSUPPORTED-003`	A 0.1-draft package asked for external capabilities. That profile grants none — no network, no files, no credentials.	§7.2, §15

`IDOP-WS-*`

Code	Meaning	Section
`IDOP-WS-ID-001`	A container identifier must be a UUID.	Containers
`IDOP-WS-LIMIT-001`	A container marker exceeds its byte limit.	Containers
`IDOP-WS-MANIFEST-001`	The workspace marker is not valid JSON, or is too large.	Containers
`IDOP-WS-MANIFEST-002`	The workspace marker does not match the schema. Unknown fields are refused rather than ignored.	Containers
`IDOP-WS-MANIFEST-003`	The workspace marker is the right shape but the wrong contents.	Containers
`IDOP-WS-MARKER-001`	That file is not a marker. A marker is `idop.workspace.json` or `idop.project.json` at a directory root.	Containers
`IDOP-WS-MARKER-002`	A container marker does not have the expected shape.	Containers
`IDOP-WS-SECRET-001`	This marker has a configuration key that names secret material. Credentials belong to the Reader; a workspace file may reference an alias, never a value.	Containers
`IDOP-WS-TIME-001`	A container timestamp must be RFC 3339 in UTC.	Containers
`IDOP-WS-UNSUPPORTED-001`	This marker declares a format or version this Reader does not implement.	Containers

`IDOP-ZIP-*`

Code	Meaning	Section
`IDOP-ZIP-001`	No end-of-central-directory record was found: the file is not a ZIP archive or is truncated.	§4.1
`IDOP-ZIP-002`	The central directory offset points outside the file.	§4.1
`IDOP-ZIP-003`	A central directory record has an invalid signature.	§4.1
`IDOP-ZIP-010`	ZIP64 structures and truncated archives are outside the profile.	§4.1
`IDOP-ZIP-011`	There are extra bytes after the archive. A polyglot file cannot be verified, so it is refused.	§4.1
`IDOP-ZIP-012`	Split and multi-part archives are outside the profile.	§4.1
`IDOP-ZIP-013`	There are extra bytes before the archive.	§4.1
`IDOP-ZIP-014`	An entry name uses non-ASCII characters without the UTF-8 flag.	§4.1
`IDOP-ZIP-015`	Encrypted ZIP entries cannot be validated before execution.	§4.1
`IDOP-ZIP-016`	Only the Store and Deflate methods are allowed.	§4.1
`IDOP-ZIP-017`	Two central directory records point at the same local header.	§4.1
`IDOP-ZIP-018`	The first entry does not start at offset 0. That is what a file appended to another format looks like.	§4.1
`IDOP-ZIP-019`	The first local entry (mimetype) carries an extra field.	§4.1
`IDOP-ZIP-020`	A local header has an invalid signature.	§4.1
`IDOP-ZIP-021`	The local and central headers disagree. That is a classic way to hide a second file, so the package is refused.	§4.1
`IDOP-ZIP-022`	A ZIP extra field is truncated.	§4.1
`IDOP-ZIP-023`	The local records do not cover the archive exactly, in central directory order, from offset 0 to the central directory: there is a gap, an overlap or a record out of order. Bytes the central directory does not account for are where a hidden second entry would sit.	§4.1
`IDOP-ZIP-024`	An entry sets general purpose bit 3, but no data descriptor with the central directory's CRC-32 and sizes follows its data.	§4.1
`IDOP-ZIP-030`	The two independent ZIP parsers disagree on the number of entries.	§4.1
`IDOP-ZIP-031`	The archive reads differently through its local and central headers.	§4.1
`IDOP-ZIP-032`	Directory entries are forbidden; a package lists files only.	§4.1
`IDOP-ZIP-033`	An entry decompressed to a different size than its headers declare.	§4.1
`IDOP-ZIP-034`	Symlinks and device files are forbidden in a package.	§4.1