Error Codes

Canonical Reference: This page provides a user-friendly summary of exit codes. For normative semantics and detailed specifications, see Error Handling Specification.

Structyl uses standard exit codes to indicate the result of commands.

Exit Codes

Code	Name	Description
0	Success	Command completed successfully
1	Failure	Build, test, or command failed
2	Configuration Error	Invalid configuration
3	Environment Error	Missing external dependency

Understanding Exit Codes

Code 0 - Success

Everything worked as expected.

structyl build && echo "Success!"

Code 1 - Failure

Your project has an issue that Structyl detected. The configuration is valid, but the build or test failed.

Examples:

• Compilation error
• Test assertion failed
• Build script returned non-zero

structyl test
if [ $? -eq 1 ]; then
    echo "Tests failed"
fi

Code 2 - Configuration Error

The Structyl configuration is invalid. Fix .structyl/config.json before proceeding.

Examples:

• Malformed JSON
• Missing required field
• Circular dependency
• Unknown toolchain
• Invalid version format

structyl: failed to load configuration: project.name: required

Code 3 - Environment Error

An external system or resource is unavailable.

Examples:

• Docker not running
• File permission denied
• Network timeout
• Missing toolchain binary

structyl: Docker is not available

Skipped Commands

Some commands are skipped rather than failed. Skip scenarios include:

• Command explicitly set to null in configuration
• Executable not found in PATH
• npm/pnpm/yarn/bun script missing from package.json

Skipped commands:

• Log warnings but do NOT fail the build
• Do NOT affect exit code (still exits 0 if no actual failure)

See Error Handling Specification for details.

Scripting with Exit Codes

structyl test
case $? in
    0) echo "All tests passed" ;;
    1) echo "Tests failed" ;;
    2) echo "Configuration error - check .structyl/config.json" ;;
    3) echo "Missing dependency - check environment" ;;
    *) echo "Unknown error" ;;
esac

Multi-Target Failures

When running commands across multiple targets:

Fail-Fast (Default)

Stops on first failure:

structyl test
# Exits immediately when first target fails

Fail-Fast Behavior

Structyl stops on the first failure when running commands across multiple targets. This fail-fast approach:

• Provides immediate feedback on failures
• Prevents cascading errors from incomplete builds
• Aligns with mise backend behavior

--continue Flag Removed

The --continue flag has been removed. Using it will result in an error.

Alternatives for continue-on-error workflows:

1. Use continue_on_error: true in CI pipeline step definitions (see CI Integration)
2. Configure individual mise tasks with shell-level error handling (e.g., || true)

Error Message Format

CLI-level errors (configuration, usage, environment):

structyl: <message>

Target-specific failures (build, test failures):

[<target>] <command>: <message>

Example - CLI error:

structyl: configuration file not found

Example - Target failure:

[cs] build: failed with exit code 1

Example - Configuration error:

structyl: failed to load configuration: project.name: required

Note: Structyl reports validation errors one at a time. Fix and re-run to see subsequent errors.

Verbosity Levels

Flag	Output
-q	Errors only
(default)	Errors + summary
-v	Full output from all targets

Recovery Strategies

Clean Build

structyl clean
structyl build

Docker Reset

structyl docker-clean
structyl build --docker

Validate Configuration

structyl config validate

See Also

• Error Handling Specification - Complete error handling semantics