abhigyanpatwari/GitNexus · error

"asyncApiSpecPath" must be a non-empty string

Error message

"asyncApiSpecPath" must be a non-empty string

What it means

The GitNexus HTTP API (createServer) validates the `asyncApiSpecPath` field in request bodies used to configure analysis targets. When the field is present but is not a string, or is an empty/whitespace-only string, the endpoint rejects the request with HTTP 400 and this message.

Source

Thrown at gitnexus/src/server/api.ts:1544

          res.status(400).json({ error: '"url" must be a string' });
          return;
        }
        if (repoLocalPath !== undefined && typeof repoLocalPath !== 'string') {
          res.status(400).json({ error: '"path" must be a string' });
          return;
        }
        if (
          springActuatorPath !== undefined &&
          (typeof springActuatorPath !== 'string' || springActuatorPath.trim().length === 0)
        ) {
          res.status(400).json({ error: '"springActuatorPath" must be a non-empty string' });
          return;
        }
        if (
          asyncApiSpecPath !== undefined &&
          (typeof asyncApiSpecPath !== 'string' || asyncApiSpecPath.trim().length === 0)
        ) {
          res.status(400).json({ error: '"asyncApiSpecPath" must be a non-empty string' });
          return;
        }

        if (!repoUrl && !repoLocalPath) {
          res.status(400).json({ error: 'Provide "url" (git URL) or "path" (local path)' });
          return;
        }

        // Token: optional, restricted charset to prevent header smuggling
        // (CRLF), bound length, and bound to github.com (see validateAnalyzeToken).
        const tokenError = validateAnalyzeToken(repoToken, repoUrl);
        if (tokenError) {
          res.status(tokenError.status).json({ error: tokenError.error });
          return;
        }

        // Path validation. The previous `normalize !== resolve` guard was inert
        // (both collapse `..` identically) and only false-rejected trailing

View on GitHub (pinned to 0d1aed942f)

Solutions

1. Omit `asyncApiSpecPath` from the request body if there is no AsyncAPI spec to analyze.
2. Provide a valid non-empty path string pointing at the AsyncAPI spec file.
3. Sanitize config before sending: map empty/blank values to undefined so the field is omitted.
4. Fix serialization so non-string values are not sent for this field.

Example fix

// before
const body = { path: '.', asyncApiSpecPath: cfg.asyncApiSpecPath ?? '' };
// after
const body = { path: '.', ...(cfg.asyncApiSpecPath ? { asyncApiSpecPath: cfg.asyncApiSpecPath } : {}) };

function validateAsyncApiSpecPath(v: unknown): string | undefined {
  if (v === undefined) return undefined;
  if (typeof v !== 'string' || v.trim().length === 0) throw new Error('asyncApiSpecPath must be a non-empty string');
  return v;
}

function isValidOptionalString(v: unknown): v is string {
  return typeof v === 'string' && v.trim().length > 0;
}

const res = await fetch(url, { method: 'POST', body: JSON.stringify(payload) });
if (res.status === 400) {
  const { error } = await res.json();
  if (error?.includes('asyncApiSpecPath')) {
    delete payload.asyncApiSpecPath; // retry without the field
  }
}

When it happens

Trigger: Sending a POST request to the analyze/index endpoint whose JSON body includes `asyncApiSpecPath` set to null, a number, a boolean, an object, "" or " " (whitespace only). The field being absent (undefined) passes validation.

Common situations: CLI or CI scripts templating an AsyncAPI spec path that resolves to empty; config files with `asyncApiSpecPath: ""` placeholders; JSON built programmatically where an unset option serializes as "".

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• "springActuatorPath" must be a non-empty string
• Uploaded folder has no usable name
• Upload must be a folder
• Parameter "${fieldName}" must be a string
• Path must not be empty

AI-assisted analysis of abhigyanpatwari/GitNexus@0d1aed942f (2026-09-08). Data as JSON: /api/errors/05f2578f409d14c8. Report an issue: GitHub.