Fission-AI/OpenSpec · error · ChangeMetadataError

Unknown schema ' '. Available

Error message

Unknown schema '${parseResult.data.schema}'. Available: ${availableSchemas.join(', ')}

What it means

ChangeMetadataError thrown by readChangeMetadata after a successful Zod parse: the metadata's schema field names a schema that listSchemas() does not know for this project. The file is structurally valid but references an unavailable schema — typically one defined elsewhere or removed.

Solutions

1. Install or restore the referenced schema in the project
2. Edit the metadata's schema field to one of the available schemas listed in the message

When it happens

Trigger: Thrown at src/utils/change-metadata.ts:140 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Fission-AI/OpenSpec@6926ccb18a (2026-08-25). Data as JSON: /api/errors/342747aaec88c571. Report an issue: GitHub.

Appendix: source

Thrown at src/utils/change-metadata.ts:140

      `Invalid YAML in metadata file: ${parseError.message}`,
      metaPath,
      parseError
    );
  }

  // Validate with Zod
  const parseResult = ChangeMetadataSchema.safeParse(parsed);
  if (!parseResult.success) {
    throw new ChangeMetadataError(
      `Invalid metadata: ${parseResult.error.message}`,
      metaPath
    );
  }

  // Validate that the schema exists
  const availableSchemas = listSchemas(projectRoot);
  if (!availableSchemas.includes(parseResult.data.schema)) {
    throw new ChangeMetadataError(
      `Unknown schema '${parseResult.data.schema}'. Available: ${availableSchemas.join(', ')}`,
      metaPath
    );
  }

  return parseResult.data;
}

export interface ResolveSchemaForChangeOptions {
  metadata?: ChangeMetadata | null;
  /** Pre-read project config; suppresses the fallback config read when provided. */
  projectConfig?: ProjectConfig | null;
}

/**
 * Resolves the schema for a change, with explicit override taking precedence.
 *
 * Resolution order:

View on GitHub (pinned to 6926ccb18a)