Error Handling Reference

Every error message that massu init, the config loader, and the atomic-write layer can surface. Each entry quotes the exact string, explains what triggered it, and states the concrete fix. Errors are grouped by the phase that produces them.

Config Validation Errors (Zod)

The config loader in packages/core/src/config.ts uses Zod to validate massu.config.yaml. On failure, it throws a single error containing all issues, prefixed with the file path.

Invalid Config Shape

Error:

Invalid massu.config.yaml at /path/to/massu.config.yaml:
  framework.type: Expected one of ["typescript", "javascript", "python", "rust", ...], received "swif"
  domains[0].routers: Expected array, received string

What it means: One or more fields failed Zod validation. The loader lists every issue with its JSON path and the expected vs received shape.

How to fix:

1. Open massu.config.yaml
2. Navigate to each field listed in the error
3. Correct the value to match the expected type/shape
4. Consult reference/config-reference for valid values per field
5. Re-run the command

Missing Required Field

Error:

Invalid massu.config.yaml at /path/to/massu.config.yaml:
  project.name: Required

What it means: A required field is absent from your config.

How to fix: Add the missing field. project.name is required; project.root defaults to "auto".

Post-Init Validation Errors

After writing massu.config.yaml, validateWrittenConfig in packages/core/src/commands/init.ts re-reads the file through the full Zod pipeline AND verifies declared paths exist on disk. On failure, the written file is removed (rmSync) and an error is thrown — no invalid config can persist.

Config File Not Found After Write

Error:

Config file does not exist after write

What it means: The atomic write layer reported success but the file is missing. Very unusual — likely a race or a filesystem issue.

How to fix:

1. Check disk space: df -h .
2. Check the directory is writable: ls -ld .
3. Re-run massu init. If it persists, file an issue with your platform and filesystem details.

paths.source Does Not Exist on Disk

Error:

paths.source 'src' does not exist on disk

What it means: Post-init validation walks paths.source and fails because the directory isn't on disk. This usually means detection picked a dominant directory that was subsequently deleted, or you hand-edited paths.source to a non-existent path.

How to fix:

1. Create the directory: mkdir -p src
2. OR edit paths.source in massu.config.yaml to an existing directory
3. Re-run massu init --force to regenerate

source_dirs Does Not Exist on Disk

Error:

framework.languages.typescript.source_dirs 'src' does not exist on disk

What it means: A per-language source dir declared in framework.languages.<lang>.source_dirs doesn't resolve to a real directory.

How to fix:

1. Create the missing directory, or
2. Remove it from framework.languages.<lang>.source_dirs, or
3. Re-run detection with massu init --force

Generated Config Invalid

Error:

Generated config invalid: <validation summary>

What it means: massu init ran detection, generated a config, but the written YAML fails its own validation. The written file has been rolled back.

How to fix: Check the underlying validation summary appended after the colon. Common causes:

• Detection produced an empty framework.languages because zero manifests were found
• A custom detection.rules entry emitted a framework name that doesn't match Zod's expected shape
• A user override in verification.<language> has a non-string value

Template Config Invalid

Error:

Template config invalid: <validation summary>

What it means: You ran massu init --template <name> but the template's massu.config.yaml doesn't pass Zod validation — likely a template has drifted out of sync with the schema.

How to fix: File an issue including the template name (python-fastapi, ts-nextjs, etc.). Workaround: use massu init without --template to run detection instead.

Atomic Write Errors

writeConfigAtomic writes to <configPath>.tmp first, parses the content, then atomically renames. On any failure path, the .tmp file is removed so the filesystem stays clean.

Generated Config Is Not a Valid YAML Object

Error:

Generated config is not a valid YAML object

What it means: The content Massu tried to write parsed as YAML but wasn't a top-level object (likely a scalar or a list). This is a bug — file an issue.

How to fix:

1. Check the tmp file was cleaned up: ls -la massu.config.yaml.tmp should return "No such file"
2. Re-run massu init
3. If reproducible, attach the project structure (language manifests, monorepo layout) to a bug report

Atomic Write Failed

Error:

atomic write failed

What it means: The underlying renameSync from <configPath>.tmp to <configPath> threw. Usually permissions or filesystem race.

How to fix:

1. Check permissions on the target directory
2. Ensure no other process is holding massu.config.yaml open
3. If the tmp file lingers, remove it: rm -f massu.config.yaml.tmp

Overwrite Protection Errors

Config Exists in --ci Mode

Error:

massu init: config exists in --ci mode (no overwrite)

What it means: You ran massu init --ci but massu.config.yaml already exists. CI mode never silently overwrites user config.

How to fix:

• Pass --force to overwrite: massu init --ci --force
• OR delete the existing config first
• OR run in interactive mode (no --ci), which will prompt with default NO

Unknown Template

Error:

Unknown template: <name>

What it means: You passed --template <name> but <name> is not one of the shipped templates.

How to fix: Use one of: python-fastapi, python-django, ts-nextjs, ts-nestjs, rust-actix, swift-ios, multi-runtime. See reference/cli-reference for the full list.

Template Copy Failed

Error:

template copy failed

What it means: The template's massu.config.yaml was found but couldn't be copied to the target path. Usually permissions or disk space.

How to fix: Check df -h . and directory permissions, then re-run.

Detection Errors

No Languages Detected

Error:

No languages detected

What it means: runDetection walked the project and found zero recognized manifests. Without at least one manifest, detection has nothing to act on.

How to fix:

• If the project is empty or new: use a template instead — massu init --template ts-nextjs (or another)
• If the project has manifests in unusual locations: move them to project root or a standard workspace layout (apps/, packages/, services/*)
• If manifests are present but malformed: check result.warnings — fix the underlying JSON/TOML parse error

buildConfigFromDetection Requires a Detection Result

Error:

buildConfigFromDetection requires a detection result

What it means: Internal error — buildConfigFromDetection() was called with null or undefined. You should never see this from massu init; if you do, file a bug.

How to fix: File an issue with your repo structure and the command you ran.

Warnings (Non-Fatal)

Warnings are written to stderr but do not abort massu init. They surface in the warnings field of DetectionResult and include:

• Malformed manifest — JSON/TOML parse error in a package.json, pyproject.toml, Cargo.toml, etc. The manifest is skipped; other manifests proceed. Fix by correcting the file or adding it to .gitignore.
• Language ambiguity — Multiple languages have similar file-count density, making the "primary" choice non-obvious. The detector picks alphabetically; review framework.primary after init and set it explicitly if needed.

Related

• auto-detection — what signals detection reads and how to override
• migration/v1-to-v2 — migration errors and rollback
• reference/config-reference — valid values for every config field
• guides/troubleshooting — broader installation and runtime issues