gatsbyjs/gatsby · critical

Missing program args

Error message

Missing program args

What it means

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.

Source

Thrown at packages/gatsby/src/services/initialize.ts:91

type WebhookBody = IDataLayerContext["webhookBody"]

export async function initialize({
  program: args,
  parentSpan,
}: IBuildContext): Promise<{
  store: Store<IGatsbyState, AnyAction>
  workerPool: WorkerPool.GatsbyWorkerPool
  webhookBody?: WebhookBody
  adapterManager?: IAdapterManager
}> {
  if (process.env.GATSBY_DISABLE_CACHE_PERSISTENCE) {
    reporter.info(
      `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.`
    )
  }
  if (!args) {
    reporter.panic(`Missing program args`)
  }

  /* Time for a little story...
   * When running `gatsby develop`, the globally installed gatsby-cli starts
   * and sets up a Redux store (which is where logs are now stored). When gatsby
   * finds your project's locally installed gatsby-cli package in node_modules,
   * it switches over. This instance will have a separate redux store. We need to
   * ensure that the correct store is used which is why we call setStore
   * (/packages/gatsby-cli/src/reporter/redux/index.js)
   *
   * This function
   * - copies over the logs from the global gatsby-cli to the local one
   * - sets the store to the local one (so that further actions dispatched by
   * the global gatsby-cli are handled by the local one)
   */
  if (args.setStore) {
    args.setStore(store)
  }

View on GitHub (pinned to 8b06340921)

Solutions

1. Ensure the program/args object is always passed when calling initialize programmatically -- typically via gatsby-cli which constructs it.
2. If using the programmatic API, follow the documented entry point that builds the program object from CLI flags or config.
3. Check for regressions in custom integrations that may have stopped forwarding the args parameter.

// Validate program args before calling initialize
function validateProgramArgs(args) {
  if (!args || typeof args !== 'object') {
    throw new Error('initialize requires a program args object')
  }
  const required = ['directory', 'argv']
  for (const key of required) {
    if (!(key in args)) {
      throw new Error('program args missing required key: ' + key)
    }
  }
}

// Type guard for program args
function isProgramArgs(args) {
  return (
    typeof args === 'object' &&
    args !== null &&
    typeof args.directory === 'string' &&
    Array.isArray(args.argv)
  )
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• gatsby <${command}> can only be run for a gatsby site. Eithe
• There was a problem loading the local ${command} command. Ga
• Unable to copy site files to .cache
• Failed to read ${siteDir}/api-runner-ssr.js
• Missing required params

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/42097f6cb94c76e8. Report an issue: GitHub.