Limits and error index

Every hard number the platform enforces, and every message it can show you, in one place. Other pages state a rule in context and link here for the number and the exact string; this page is the normative home for both.

Paste a message you got into your browser’s find-in-page. Each row names the cause and links to the page that explains the fix.

Enforcement levels

This legend is used throughout the book. Four levels, and only four:

The three gates a publish ERROR can come from

The source-zip audit and the built-zip audit share one widget-summary validator, so a widgets[] mistake fails at gate 1 (fast) rather than gate 3 (slow). Central re-validates the same rules server-side; the browser audit is UX, not the authority.

Limits

Manifest counts and sizes

Field-by-field rules for these live in Manifest: root fields, Manifest: widget summary and Layout widgets.

Source zip

The zip you upload. Rules are checked in your browser before a single byte is transmitted.

Forbidden content and the required root files are in Packaging and publishing rules; their exact strings are indexed under “Source-zip audit” below.

Built zip and its size warnings

The zip the reviewer produces from your source. You never upload it, but its limits decide whether your reviewed plugin actually goes live.

Size warnings — never blocking, and visible only to the reviewer:

// src/lib/plugin-zip.ts (auditBuildZip) — the three soft thresholds, per widget
if (plan.js)  logical.push({ kind: "client bundle", name: plan.js,  warn: 1_500_000 });
if (plan.css) logical.push({ kind: "stylesheet",    name: plan.css, warn:   512_000 });
if (plan.ssr) logical.push({ kind: "SSR bundle",    name: plan.ssr, warn: 1_000_000 });
// → `dist/{name} is {n} MB.`
// → `dist/{name} is {n} MB — over the renderer's 1 MB cache threshold (slower cold SSR).`

The 1 MB SSR threshold is not cosmetic: a bundle over 1,000,000 bytes is skipped by the renderer’s Redis bundle cache entirely, so every cold lambda re-fetches it from the CDN.

Runtime bounds

Every timeout, cap and cache window the platform applies to a plugin at run time.

Public-API rate limiting is a separate contract — see Public API. Cache-Control headers on published files are in Keywords, assets and URLs.

Two of these bounds also apply on your laptop (widget-core 0.12.2+): npm run dev:ssr applies the same 5000 ms module-scope budget and the same 5-hop externalFetch redirect cap. Neither is adjustable from npm run dev:ssr — SSRDevServerOptions exposes no knob for either. Only a hand-rolled renderPluginSSR / evaluatePluginSSR call can move the module-scope budget, via execTimeoutMs (SDK reference); the redirect cap is fixed everywhere. Nothing else in the table has a local equivalent — the caches, the page TTL and the purge budgets are all platform-side.

Error index

1. Source-zip audit (your browser, before upload)

Structure and content of the zip itself.

__MACOSX/ entries and .DS_Store are ignored. A single top-level wrapper folder (what macOS “Compress” produces) is tolerated, and every path rule is then applied relative to it.

Manifest identity and shape:

Widget summaries — Shape: Suite. These run in both the source-zip and built-zip audits, and central mirrors them:

Presets — Shape: Suite (0.11.0+):

Preset semantics are in Layout widgets.

2. Central submit API (after upload)

Every response uses central’s coded envelope.

Only VERSION_NOT_GREATER, SLUG_TAKEN and SLUG_RESERVED can surprise you after a clean browser audit — the browser only checks version shape, never monotonicity. See Preflight and submit.

3. Built-zip audit (publish; reviewer-visible only)

These block your reviewed plugin from going live. You will normally learn about them through review notes.

media/ is authored content, not build output. Anything you declare — icons, cover, screenshots, READMEs — must be committed and present in your source zip, or these errors fire at publish, long after you were told the submission looked fine.

Built-zip warnings (never blocking):

4. Central publish and rollback

See Publishing, versions and rollback and Install, customers and kill switches.

5. Dashboard operator messages

Shown to whoever drives the upload. Quoted because you will see them relayed to you.

Retrying a failed publish is always safe: the root manifest.json is uploaded last and is both the immutability sentinel and the verification target, so a publish that dies mid-upload leaves nothing live.

6. Renderer SSR failures

A plugin failure never takes the page down. The widget’s markup is replaced by a hidden breadcrumb node:

// packages/homerunner-renderer/lib/render-utils.tsx (widgetFailureNode)
const safe = `HR widget failed — type="${info.type}"${info.id ? ` id="${info.id}"` : ""}: ${info.reason}`
    .replace(/-{2,}/g, "-")
    .replace(/>/g, ">");
return (
    <div
        data-hr-widget-error={info.type}     // the widget KEYWORD, not the failure kind
        hidden
        dangerouslySetInnerHTML={{ __html: `<!-- ${safe} -->` }}
    />
);

View-source and search for data-hr-widget-error to read the reason. A page containing one is flagged degraded, so its cache TTL drops from 24 h to 60 s.

Not supported yet. A content widget that throws during render becomes a failure node and the rest of the page survives. A layout component that throws during render is not contained — its element is rendered later in the page-level renderToString, which has no try/catch, so the whole render endpoint 500s. Never throw in a layout’s render path.

Renderer-side log lines you can ask an operator to grep, by prefix:

• [plugin] Fetching SSR bundle: {url} — a cold load (no in-process module, no Redis entry).
• [plugin] SSR bundle from Redis: {url} — L2 hit.
• [plugin] Failed to load SSR bundle from {url}: {msg} — the load threw; the widget fails.
• [plugin] Loaded "{type}" ({id}) via SSR bundle — success.
• [plugin] No manifest entry for "{type}". Skipping. — keyword/shape mismatch.
• [plugin] "{type}" is a layout widget — it must render as a layout entry (with slots), not content. Skipping.
• [widget] SSR prefetch FAILED — shipping loading markup. key={hash} error={msg} — a prefetch error is swallowed, the widget still renders, and the page is marked degraded.
• [layout] Slot "{name}" references missing widget {id} — a stale slot binding.
• [layout] Plugin layout widgets are not supported in slots yet. Slot "{name}" references "{keyword}". Skipping.
• [layout] Failed to prepare "{type}" ({id}): {msg} — precedes a layout SSR data prep failed breadcrumb.

Your own console.* calls go straight to renderer stdout — the host console is injected into the sandbox.

7. SSR sandbox throws

Thrown inside the node:vm context. Each one ends up as a SSR bundle failed to load or SSR data prep failed reason above, but the text lands in the renderer’s logs. The local harness is a port of the same sandbox and raises the same strings — the require whitelist’s seventh entry, the externalFetch block messages and the execution timeout all reached it in widget-core 0.12.2. The divergences that remain are in Previewing SSR locally.

// packages/homerunner-renderer/lib/plugin-federation.ts (buildEnforcedFetch)
const host = u.hostname.toLowerCase();
const hostPort = u.port ? `${host}:${u.port}` : host;
const allowed = host === centralHost() || declared.has(host) || declared.has(hostPort);
// a declared entry may be "api.example.com" (any port) or "api.example.com:8443"

8. Browser: mount and runtime

data-hr-error on the host element — the complete vocabulary:

Console strings, by prefix:

9. The /p/ asset proxy

GET {assets}/p/{slug}/{file} — {file} is the dist-relative name (acme.iife.js for v1, hero/hero.iife.js for a suite). Full contract in Keywords, assets and URLs.

10. Dashboard config panel

11. Local build and dev tooling

Build CLI (hr-widget-build, run for you by npm run build):

Scaffolder (create-hr-plugin). Every row but the last is checked before a single file is written, and exits 1:

SSR preview (npm run dev:ssr). The first row is a red panel on every scenario tab. The rest are resolved at boot, before the server starts (widget-core 0.12.2+): the suite scaffold’s scripts/dev-ssr.mts prints them and exits 1, while a direct createSSRDevServer call throws the same string:

More symptom-first triage in Troubleshooting.

Known gaps

Not supported yet. Built-zip audit results — errors and warnings — are visible only in the reviewer’s console. You cannot run that audit yourself, and nothing forwards its warnings to you. Treat the size thresholds and the configSchema warnings above as a self-checklist.

Not supported yet. There is no notification of any review outcome. No email, no in-app message. Check Dashboard → Plugins → My plugins.

Not supported yet. accepts: ["layout"] can never match. The slot picker always excludes layout-category candidates before the accepts predicate runs, and accepts is not validated at publish at all — it is advisory (unvalidated).

Not supported yet. Preset slot keys are never validated against the layout’s declared slot names. A typo creates a binding the layout will never render, with no error at any gate.

Not supported yet. prefill keywords are shape-validated only (/^[a-z][a-z0-9-]{0,63}$/) — never checked against the real system-widget keyword list. An invented keyword passes publish and is reported at creation time as {keyword}: not a widget this platform can create.

Not supported yet. externalFetch is advisory (unvalidated) at publish: any list of strings passes. It is enforced only at SSR runtime, so a typo’d host is discovered as a blocked fetch on a live page.

Not supported yet. replacedBy is declared, diffed at review, and read by no runtime or UI code — it is surfaced nowhere.

Not supported yet. A pre-release version (1.0.0-rc.1) passes both the browser audit and central, but every immutability optimisation keys off a bare X.Y.Z path segment. Publishing one silently drops you to TTL-bound caching and /p/-proxied asset URLs everywhere. Use plain three-part versions.