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.

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
• "branch" must be a string
• Missing "cypher" in request body
• Missing path
• Parameter " " must be a string

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

Appendix: source

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

          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;
        }

        // Branch: optional index-branch selector, validated with the same rules
        // as the CLI's `--branch` so both entry points accept the same refs.
        // Rejecting here (rather than letting the clone fail) keeps a malformed
        // ref from ever reaching `git`.
        if (repoBranch !== undefined && typeof repoBranch !== 'string') {
          res.status(400).json({ error: '"branch" must be a string' });
          return;
        }
        let analyzeBranch: string | undefined;
        if (repoBranch !== undefined) {

View on GitHub (pinned to ac9a4e9abd)