# Schema Error Codes Reference
This document provides a comprehensive reference for all error codes that can be generated by the `backbone-schema` CLI.
## Table of Contents
- [Error Categories](#error-categories)
- [Parse Errors (E0xx)](#parse-errors-e0xx)
- [Type Errors (E1xx)](#type-errors-e1xx)
- [Reference Errors (E2xx)](#reference-errors-e2xx)
- [State Machine Errors (E3xx)](#state-machine-errors-e3xx)
- [Permission Errors (E4xx)](#permission-errors-e4xx)
- [Flow Errors (E5xx)](#flow-errors-e5xx)
- [Generation Errors (E6xx)](#generation-errors-e6xx)
- [Troubleshooting Guide](#troubleshooting-guide)
---
## Error Categories
| E0xx | Parse | Lexer and syntax errors |
| E1xx | Type | Type resolution and validation |
| E2xx | Reference | Model, field, and cross-module references |
| E3xx | State Machine | State and transition validation |
| E4xx | Permission | Access control and role validation |
| E5xx | Flow | Flow orchestration validation |
| E6xx | Generation | Code generation errors |
---
## Parse Errors (E0xx)
### E001: Lexer Error
**Description:** The lexer encountered an invalid character or token.
**Example:**
```yaml
models:
- name: User
fields:
email: @@@invalid # E001: Invalid characters
```
**Solution:** Check for invalid characters or malformed tokens in your schema.
---
### E002: Syntax Error
**Description:** The parser encountered unexpected syntax.
**Example:**
```yaml
models:
- name: User
fields
email: string # E002: Missing colon after 'fields'
```
**Solution:** Verify YAML syntax, ensure proper indentation, and check for missing colons.
---
### E003: Unexpected Token
**Description:** The parser found a token where a different one was expected.
**Example:**
```yaml
models:
- name: 123User # E003: Expected identifier, got number
```
**Solution:** Model and field names must start with a letter and contain only alphanumeric characters.
---
### E004: Unexpected End of File
**Description:** The file ended unexpectedly while parsing a construct.
**Example:**
```yaml
models:
- name: User
fields:
# File ends here without defining fields
```
**Solution:** Complete all schema definitions before the end of the file.
---
### E005: Invalid Type
**Description:** An unrecognized type was specified.
**Example:**
```yaml
fields:
data: unknownType # E005: 'unknownType' is not a valid type
```
**Solution:** Use a valid primitive type, enum, or model reference. See [TYPES.md](./TYPES.md) for available types.
---
### E006: Invalid Attribute
**Description:** An unrecognized or malformed attribute was specified.
**Example:**
```yaml
fields:
email:
type: string
attributes: ["@unknownAttr"] # E006: Unknown attribute
```
**Solution:** Check [RULE_FORMAT_MODELS.md](./RULE_FORMAT_MODELS.md#field-attributes) for valid validation attributes.
---
## Type Errors (E1xx)
### E100: Unknown Type
**Description:** A type reference could not be resolved.
**Example:**
```yaml
fields:
status:
type: UserStatus # E100: 'UserStatus' enum not defined
```
**Solution:** Define the enum or custom type before referencing it.
```yaml
enums:
- name: UserStatus
values: [active, inactive]
models:
- name: User
fields:
status:
type: UserStatus # Now valid
```
---
### E101: Type Mismatch
**Description:** A value or expression has an incompatible type.
**Example:**
```yaml
fields:
age:
type: int
attributes: ["@default('not a number')"] # E101: String for int field
```
**Solution:** Ensure default values and expressions match the field type.
---
### E102: Invalid Attribute for Type
**Description:** An attribute was applied to an incompatible type.
**Example:**
```yaml
fields:
count:
type: int
attributes: ["@email"] # E102: @email not valid for int
```
**Solution:** Use type-appropriate attributes. `@email` is only valid for string fields.
---
### E103: Array Type Error
**Description:** Invalid array type specification.
**Example:**
```yaml
fields:
tags:
type: "[]" # E103: Array must have element type
```
**Solution:** Specify the array element type: `type: string[]` or `type: Tag[]`.
---
## Reference Errors (E2xx)
### E200: Unknown Model
**Description:** A model reference could not be resolved.
**Example:**
```yaml
relations:
author:
type: belongs_to
model: UnknownModel # E200: Model not found
```
**Solution:** Ensure the referenced model exists in the same module or import it.
```yaml
# user.model.yaml
external_imports:
posts: Post
relations:
posts:
type: has_many
model: Post # Now valid if Post is defined in posts module
```
---
### E201: Unknown Field
**Description:** A field reference could not be resolved.
**Example:**
```yaml
indexes:
- name: idx_email
fields: [email_address] # E201: 'email_address' not defined
```
**Solution:** Use the correct field name as defined in the model.
---
### E202: Circular Reference
**Description:** A circular dependency was detected between models.
**Example:**
```yaml
# user.model.yaml
relations:
profile:
type: has_one
model: Profile
# profile.model.yaml
relations:
user:
type: belongs_to
model: User
settings:
type: has_one
model: Settings
# settings.model.yaml
relations:
user:
type: belongs_to
model: User # E202: Circular: User -> Profile -> Settings -> User
```
**Solution:** Review your relation structure and break circular dependencies.
---
### E203: Invalid Cross-Module Reference
**Description:** A cross-module reference is invalid or not imported.
**Example:**
```yaml
relations:
posts:
type: has_many
model: posts.Post # E203: 'posts' module not imported
```
**Solution:** Add the module to `external_imports` in your schema.
---
## State Machine Errors (E3xx)
### E300: Invalid Transition
**Description:** A state transition is not allowed.
**Example:**
```yaml
states:
values:
draft: {}
published: {}
archived: {}
transitions:
publish:
from: archived # E300: Can't publish from archived
to: published
```
**Solution:** Review your state machine design and ensure transitions make logical sense.
---
### E301: Unreachable State
**Description:** A state cannot be reached from any other state.
**Example:**
```yaml
states:
values:
draft: {}
published: {}
orphaned: {} # E301: No transition leads to 'orphaned'
transitions:
publish:
from: draft
to: published
```
**Solution:** Add a transition to reach the orphaned state or remove it.
---
### E302: Missing Initial State
**Description:** No initial state is defined for the state machine.
**Example:**
```yaml
states:
field: status
values:
published: {}
archived: {}
# E302: No state marked as initial
```
**Solution:** Ensure the first state or one marked with `initial: true` exists.
```yaml
states:
values:
draft:
initial: true # Or just make it first
published: {}
```
---
### E303: Multiple Final States Conflict
**Description:** Conflicting final state definitions.
**Solution:** Review which states should be terminal (no outgoing transitions).
---
### E304: Missing State Field
**Description:** The workflow references a status field not in the model.
**Example:**
```yaml
# workflow references 'status' field
states:
field: status # E304: 'status' not in User model
```
**Solution:** Add the status field to your model.
---
## Permission Errors (E4xx)
### E400: Unknown Role
**Description:** A permission references an undefined role.
**Example:**
```yaml
permissions:
superadmin: # E400: Role 'superadmin' not defined
allow: [create, read, update, delete]
```
**Solution:** Use standard roles (admin, user, guest) or define custom roles.
---
### E401: Conflicting Permissions
**Description:** A role has conflicting allow and deny rules.
**Example:**
```yaml
permissions:
editor:
allow: [update]
deny: [update] # E401: 'update' both allowed and denied
```
**Solution:** Remove the conflicting permission from either allow or deny.
---
### E402: Invalid Permission Action
**Description:** An unrecognized action was specified.
**Example:**
```yaml
permissions:
admin:
allow: [create, read, modify] # E402: 'modify' not valid
```
**Valid Actions:**
- `create` - Create new records
- `read` - View records
- `update` - Modify existing records
- `delete` - Soft delete records
- `list` - List/query records
- `restore` - Restore deleted records
- `*` - All actions
---
### E403: Invalid Field Restriction
**Description:** Field-level permission references invalid fields.
**Example:**
```yaml
permissions:
user:
allow:
read:
only: [unknown_field] # E403: 'unknown_field' doesn't exist
```
**Solution:** Use valid field names from the model.
---
## Flow Errors (E5xx)
### E500: Duplicate Step Name
**Description:** Two steps in a flow have the same name.
**Example:**
```yaml
steps:
- name: validate
action: validate_order
- name: validate # E500: Duplicate step name
action: check_inventory
```
**Solution:** Use unique step names throughout the flow.
---
### E501: Invalid Step Reference
**Description:** A step references a non-existent step.
**Example:**
```yaml
steps:
- name: start
on_success:
next: process_payment # E501: 'process_payment' not defined
```
**Solution:** Ensure all referenced steps exist in the flow.
---
### E502: Missing Terminal Step
**Description:** A flow has no terminal step (no way to complete).
**Example:**
```yaml
steps:
- name: process
action: do_something
on_success:
next: process # E502: Infinite loop, no terminal
```
**Solution:** Add a terminal step to end the flow.
```yaml
steps:
- name: process
action: do_something
on_success:
next: complete
- name: complete
type: terminal
status: success
```
---
### E503: Unreachable Step
**Description:** A step cannot be reached from the flow entry point.
**Example:**
```yaml
steps:
- name: start
action: begin
on_success:
next: end
- name: orphan # E503: No path leads to 'orphan'
action: never_called
- name: end
type: terminal
```
**Solution:** Connect the step to the flow or remove it.
---
### E504: Invalid Compensation
**Description:** Compensation configuration is invalid.
**Example:**
```yaml
compensation:
- action: rollback
entity: UnknownEntity # E504: Entity not found
```
**Solution:** Use valid entity names and actions in compensation.
---
### E505: Invalid Parallel Branch
**Description:** A parallel step has invalid branch configuration.
**Example:**
```yaml
steps:
- name: parallel_work
type: parallel
branches: [] # E505: At least one branch required
```
**Solution:** Define at least one branch in parallel steps.
---
## Generation Errors (E6xx)
### E600: Template Error
**Description:** A code generation template failed.
**Solution:** This is typically an internal error. Please report it with your schema.
---
### E601: IO Error
**Description:** Failed to write generated files.
**Example:**
```
E601: Cannot write to /readonly/directory/user.rs
```
**Solution:** Check file permissions and ensure the output directory exists and is writable.
---
### E602: Generation Error
**Description:** Code generation failed for a specific reason.
**Solution:** Check the error message for details about what failed.
---
## Troubleshooting Guide
### Common Issues
#### 1. "Unknown type" errors
```bash
backbone-schema schema validate mymodule
Error: E100: Unknown type 'CustomType'
```
**Fix:** Check that:
- The type is defined as an enum in your schema
- Cross-module types are imported via `external_imports`
- Type names are spelled correctly (case-sensitive)
#### 2. YAML indentation errors
```bash
Error: E002: Syntax error at line 5
```
**Fix:**
- Use spaces, not tabs, for indentation
- Maintain consistent 2-space indentation
- Check for missing colons after keys
#### 3. Circular reference detection
```bash
Error: E202: Circular reference detected: User -> Profile -> User
```
**Fix:**
- Review your model relationships
- Consider using IDs instead of embedded objects
- Break the cycle by removing one direction of the relationship
### Getting Help
If you encounter an error not listed here:
1. Run with verbose output: `backbone-schema schema validate mymodule --verbose`
2. Check the schema documentation: [RULE_FORMAT_MODELS.md](./RULE_FORMAT_MODELS.md), [RULE_FORMAT_HOOKS.md](./RULE_FORMAT_HOOKS.md), [RULE_FORMAT_WORKFLOWS.md](./RULE_FORMAT_WORKFLOWS.md)
3. Report issues at: https://github.com/anthropics/claude-code/issues
### Error Message Format
Errors are displayed with source context:
```
error in user.model.yaml:
E201: Unknown field 'email_address' in model 'User'
5 │ indexes:
6 │ - name: idx_email
7 │ fields: [email_address]
│ ^
8 │
```
The caret (`^`) points to the exact location of the error.