{"record":{"id":"42097f6cb94c76e8","repo":"gatsbyjs/gatsby","slug":"missing-program-args","errorCode":null,"errorMessage":"Missing program args","messagePattern":"Missing program args","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/gatsby/src/services/initialize.ts","lineNumber":91,"sourceCode":"\ntype WebhookBody = IDataLayerContext[\"webhookBody\"]\n\nexport async function initialize({\n  program: args,\n  parentSpan,\n}: IBuildContext): Promise<{\n  store: Store<IGatsbyState, AnyAction>\n  workerPool: WorkerPool.GatsbyWorkerPool\n  webhookBody?: WebhookBody\n  adapterManager?: IAdapterManager\n}> {\n  if (process.env.GATSBY_DISABLE_CACHE_PERSISTENCE) {\n    reporter.info(\n      `GATSBY_DISABLE_CACHE_PERSISTENCE is enabled. Cache won't be persisted. Next builds will not be able to reuse any work done by current session.`\n    )\n  }\n  if (!args) {\n    reporter.panic(`Missing program args`)\n  }\n\n  /* Time for a little story...\n   * When running `gatsby develop`, the globally installed gatsby-cli starts\n   * and sets up a Redux store (which is where logs are now stored). When gatsby\n   * finds your project's locally installed gatsby-cli package in node_modules,\n   * it switches over. This instance will have a separate redux store. We need to\n   * ensure that the correct store is used which is why we call setStore\n   * (/packages/gatsby-cli/src/reporter/redux/index.js)\n   *\n   * This function\n   * - copies over the logs from the global gatsby-cli to the local one\n   * - sets the store to the local one (so that further actions dispatched by\n   * the global gatsby-cli are handled by the local one)\n   */\n  if (args.setStore) {\n    args.setStore(store)\n  }","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/src/services/initialize.ts#L73-L109","documentation":"The initialize function is the core bootstrap entry point. It requires a program/args object containing CLI flags and configuration (the IBuildContext program field). If args is null or undefined, Gatsby cannot proceed with any initialization and panics immediately.","triggerScenarios":"Calling initialize({}) or initialize() directly without passing the program args object. An internal state machine or test harness invoking initialize without constructing the program object. A CLI integration bug where args are not forwarded.","commonSituations":"Programmatic API misuse -- calling Gatsby's internal initialize without proper args. A custom script or integration that bypasses the normal CLI flow. A bug in a Gatsby wrapper or CI tool that drops the program argument.","solutions":["Ensure the program/args object is always passed when calling initialize programmatically -- typically via gatsby-cli which constructs it.","If using the programmatic API, follow the documented entry point that builds the program object from CLI flags or config.","Check for regressions in custom integrations that may have stopped forwarding the args parameter."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Validate program args before calling initialize\nfunction validateProgramArgs(args) {\n  if (!args || typeof args !== 'object') {\n    throw new Error('initialize requires a program args object')\n  }\n  const required = ['directory', 'argv']\n  for (const key of required) {\n    if (!(key in args)) {\n      throw new Error('program args missing required key: ' + key)\n    }\n  }\n}","typeGuard":"// Type guard for program args\nfunction isProgramArgs(args) {\n  return (\n    typeof args === 'object' &&\n    args !== null &&\n    typeof args.directory === 'string' &&\n    Array.isArray(args.argv)\n  )\n}","tryCatchPattern":null,"preventionTips":["Always construct the program args object before calling initialize.","Use the official gatsby-cli entry point which builds args correctly.","Do not call internal bootstrap functions directly without proper context."],"tags":["bootstrap","initialization","program-args","internal-api"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}