mastra-ai/mastra · warning · ApiCliError

SCHEMA_UNAVAILABLE

SCHEMA_UNAVAILABLE

Error message

SCHEMA_UNAVAILABLE: This command does not accept JSON input

What it means

getCommandSchema fetches the route schema (for validation/verbose mode) but first checks descriptor.acceptsInput. Commands that take no JSON input cannot have a meaningful input schema, so the CLI throws SCHEMA_UNAVAILABLE with 'This command does not accept JSON input' instead of fetching a manifest.

Source

Thrown at packages/cli/src/commands/api/schema.ts:9

import { fetchSchemaManifest } from './client.js';
import { ApiCliError } from './errors.js';
import { LEARNING_ROUTE_SCHEMAS } from './learning-route-metadata.js';
import type { ResolvedTarget } from './target.js';
import type { ApiCommandDescriptor, ApiCommandExample } from './types.js';

export async function getCommandSchema(descriptor: ApiCommandDescriptor, target: ResolvedTarget): Promise<unknown> {
  if (!descriptor.acceptsInput) {
    throw new ApiCliError('SCHEMA_UNAVAILABLE', 'This command does not accept JSON input');
  }

  // Learning routes live on the Mastra platform learning endpoint, which does
  // not expose a schema manifest; resolve their hand-authored schemas locally.
  const learningSchema = (
    LEARNING_ROUTE_SCHEMAS as Partial<
      Record<string, (typeof LEARNING_ROUTE_SCHEMAS)[keyof typeof LEARNING_ROUTE_SCHEMAS]>
    >
  )[`${descriptor.method} ${descriptor.path}`];
  if (learningSchema) {
    return buildRouteSchema(descriptor, learningSchema);
  }

  const manifest = await fetchSchemaManifest(target.baseUrl, target.headers, target.timeoutMs, target.apiPrefix);
  if (!manifest || typeof manifest !== 'object' || !Array.isArray((manifest as { routes?: unknown }).routes)) {
    throw new ApiCliError('SCHEMA_UNAVAILABLE', 'Target server returned an invalid schema manifest', {
      reason: 'invalid_manifest',
    });

View on GitHub (pinned to 75dd419e61)

Solutions

1. Only request schemas for commands that document JSON input support
2. Drop the --input/--schema flag for this command and pass any identifiers as positional arguments
3. Check the command's help/descriptor to confirm acceptsInput
4. Update scripts to skip schema retrieval for body-less commands

Example fix

// before
mastra api agents list --schema
// after
mastra api agents list

if (!commandDescriptor.acceptsInput) {
  // skip --input/--schema handling entirely
  return runCommandWithoutBody(commandDescriptor);
}

function acceptsJsonInput(d: { acceptsInput?: boolean }): boolean { return d.acceptsInput === true; }

try { await showSchema(cmd); } catch (e) { if (String(e).includes('SCHEMA_UNAVAILABLE')) return null; throw e; }

When it happens

Trigger: Requesting a schema (e.g. `mastra api <cmd> --schema` or verbose schema display) for a command whose descriptor has acceptsInput: false — typically GET/list commands with no body, or running parse-with-input style flows against such commands.

Common situations: Assuming every subcommand supports --input/--show-schema; scripting a loop that requests schemas for all commands including input-less ones; a descriptor marked acceptsInput:false after a version change renamed or restructured a command.

Related errors

• Sandbox provider "${config.sandbox.provider}" does not suppo
• ${label} contains an unsupported field.
• Invalid --region "${region}". Expected one of: eu, us.
• ${err instanceof Error ? err.message : String(err)}\nYou can
• No organization matched --org "${value}". Available: ${avail

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/106e8995c571a748. Report an issue: GitHub.