nexu-io/open-design · error · Error

brand.json not found in the extraction project — the agent h

Error message

brand.json not found in the extraction project — the agent has not written the design system yet.

What it means

Thrown by finalizeBrand when readProjectTextOrNull(projectsRoot, projectId, 'brand.json') returns null, meaning the backing project has no brand.json. finalizeBrand is meant to run after the extraction agent writes its output; this null result means the agent never wrote the file (still running, crashed, or never started).

Source

Thrown at apps/daemon/src/brands/index.ts:1338

/**
 * Finalize an agent-extracted brand: read `brand.json` (+ optional BRAND.md,
 * logos, fonts) the agent wrote into the backing project, validate it, derive
 * the deterministic brand-system artifacts, and register the `user:<id>`
 * design system. Marks the brand `ready`. Throws with a precise message when
 * the agent output is missing or invalid.
 */
export async function finalizeBrand(
  opts: FinalizeBrandOptions,
): Promise<BrandFinalizeResponse> {
  const { id, brandsRoot, projectsRoot } = opts;
  const meta = readMeta(brandsRoot, id);
  if (!meta) throw new Error(`brand not found: ${id}`);
  const projectId = opts.projectId ?? meta.projectId ?? brandProjectId(id);

  const brandJsonRaw = await readProjectTextOrNull(projectsRoot, projectId, 'brand.json');
  if (brandJsonRaw === null) {
    throw new Error(
      'brand.json not found in the extraction project — the agent has not written the design system yet.',
    );
  }
  let parsed: unknown;
  try {
    parsed = JSON.parse(brandJsonRaw);
  } catch {
    const block = extractJsonBlock(brandJsonRaw);
    if (block === null) throw new Error('brand.json is not valid JSON.');
    parsed = block;
  }
  let brand: Brand;
  try {
    brand = validateBrand(parsed, meta.sourceUrl);
  } catch (err) {
    throw new Error(`brand.json failed validation: ${errorMessage(err)}`);
  }

View on GitHub (pinned to 5be4028344)

Solutions

1. Wait until the extraction run reaches a terminal status, then finalize.
2. Inspect the project run logs to see why the agent did not write brand.json, and re-run the extraction if it crashed.
3. If the agent is genuinely finished but produced no output, re-prompt or re-trigger the extraction.

const brandJsonRaw = await readProjectTextOrNull(projectsRoot, projectId, 'brand.json');
if (brandJsonRaw === null) {
  throw new ConflictError('Extraction is not finished yet — brand.json has not been written.');
}

try {
  await finalizeBrand(opts);
} catch (err) {
  if (err instanceof Error && err.message.includes('agent has not written the design system yet')) {
    return conflict('The extraction agent has not produced brand.json yet. Wait for it to finish, then retry.');
  }
  throw err;
}

When it happens

Trigger: Calling finalize before the extraction agent reaches a terminal state; the agent errored mid-run without writing brand.json; the project was just created and the agent has not been dispatched yet.

Common situations: User clicks Finalize too early; the agent process was killed; an upstream provider error aborted the run before output was produced.

Related errors

• brand.json is not valid JSON.
• brand not found: ${opts.id}
• brand not found: ${id}
• brand.json failed validation: ${errorMessage(err)}
• Could not fetch ${url} — the site may block server-side requ

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/b8d7ebd28cd6d744. Report an issue: GitHub.