What causes "Failed to seed CEO instructions:" in paperclipai/paperclip?

Open browser devtools Network tab, find the failing /api/.../agents/{id}/instructions request and read the HTTP status — that is the real error (the warn only wraps it).

paperclipai/paperclip · warning

Failed to seed CEO instructions:

Error message

Failed to seed CEO instructions:

What it means

Logged from the OnboardingWizard's first-agent setup: after agentsApi.hire() and approval succeed, the wizard fetches the CEO instructions bundle (agentsApi.instructionsBundle) and saves a seeded instructions file (agentsApi.saveInstructionsFile). If either API call rejects, the catch logs this warning and deliberately continues to step 5 — per the in-code comment, the failure is non-fatal because the hired agent can still run with adapter defaults.

Source

Thrown at ui/src/components/OnboardingWizard.tsx:1212

        const bundle = await agentsApi.instructionsBundle(agent.id, createdCompanyId);
        await agentsApi.saveInstructionsFile(
          agent.id,
          {
            path: bundle.entryFile,
            content: composeCeoInstructions({
              companyName,
              companyGoal,
              growPath: onboardingPath === "grow",
              growWorkflows,
              growPainPoints,
              growAutomate,
              q1, q2, q3, q4,
            }),
          },
          createdCompanyId,
        );
      } catch (err) {
        console.warn("Failed to seed CEO instructions:", err);
      }

      if (!stillTheSameCompany(createdCompanyId)) return;
      setCreatedAgentId(agent.id);
      // Advance to the Review step — the lead is now online. The user drives
      // strategy + hiring from the planning chat after "Get started".
      setStep(5);
    } catch (err) {
      setError(err instanceof Error ? err.message : "Failed to create agent");
    } finally {
      setLoading(false);
    }
  }

  async function handleUnsetAnthropicApiKey() {
    if (!createdCompanyId || unsetAnthropicLoading) return;
    setUnsetAnthropicLoading(true);
    setError(null);

View on GitHub (pinned to a7e689b3c3)

Solutions

Open browser devtools Network tab, find the failing /api/.../agents/{id}/instructions request and read the HTTP status — that is the real error (the warn only wraps it).
Confirm the API is reachable: curl http://localhost:3100/api/health.
If 401/403: log in again and restart onboarding.
If the agent was created despite the warning: seed the CEO instructions manually from the agent's instructions page in the board UI.
Check server logs for the 5xx root cause (workspace path, permissions) if the status is 500.

Example fix

// before
try {
  const bundle = await agentsApi.instructionsBundle(agent.id, createdCompanyId);
  await agentsApi.saveInstructionsFile(agent.id, { path: bundle.entryFile, content }, createdCompanyId);
} catch (err) {
  console.warn("Failed to seed CEO instructions:", err);
}

// after — same non-fatal contract, but the user is told instead of only the console
try {
  const bundle = await agentsApi.instructionsBundle(agent.id, createdCompanyId);
  await agentsApi.saveInstructionsFile(agent.id, { path: bundle.entryFile, content }, createdCompanyId);
} catch (err) {
  console.warn("Failed to seed CEO instructions:", err);
  setSeedInstructionsNotice("Agent created, but its instruction file could not be seeded. Edit it from the agent page.");
}

Defensive patterns

Strategy: try-catch

Validate before calling

const health = await fetch(`${apiBase}/api/health`);
if (!health.ok) throw new Error(`API unreachable (${health.status}) — fix connectivity before onboarding`);

Type guard

const isApiError = (e: unknown): e is { status?: number; message: string } =>
  typeof e === "object" && e !== null && "message" in e;

Try / catch

try {
  const bundle = await agentsApi.instructionsBundle(agent.id, companyId);
  await agentsApi.saveInstructionsFile(agent.id, { path: bundle.entryFile, content }, companyId);
} catch (err) {
  // Non-fatal by design: the agent exists. Log, optionally notify, continue the wizard.
  console.warn("Failed to seed CEO instructions:", err instanceof Error ? err.message : err);
}

Prevention

Keep the API server running and the auth session fresh for the whole wizard (it makes several sequential calls after hire).
Treat this warn as 'agent created, instructions missing' — verify the instructions file from the agent page after onboarding.
Watch the Network tab during onboarding; the wrapped error's HTTP status is the actionable part.
In e2e tests, assert on the instructions API directly so this path is covered.

When it happens

Trigger: Running the onboarding wizard, completing agent hire, then the GET instructions-bundle or POST save-instructions-file request failing: API server restart mid-wizard, 401 from an expired session, 404 for a just-deleted agent/company, or a 5xx when the server cannot write the instructions file to the workspace.

Common situations: Dev server restarted while the wizard was open; auth token expired during a long wizard session; company context switched (stillTheSameCompany race); server-side filesystem/permission error writing the agent instructions file.

Related errors

AI-assisted analysis of paperclipai/paperclip@a7e689b3c3 (2026-08-18). Data as JSON: /api/errors/4e64f259141e70a1. Report an issue: GitHub.