Error Code Reference

Complete catalog of pytest-jux error messages, causes, and solutions

Overview

This reference catalogs all error messages, exceptions, and exit codes in pytest-jux. Use this guide to troubleshoot issues and understand error messages.

Error Categories

Configuration Errors: Invalid configuration or missing settings
File Errors: File not found, permission denied
Cryptographic Errors: Key/certificate issues, signing failures
Validation Errors: Invalid XML, schema violations
Storage Errors: Storage/caching failures
CLI Errors: Command-line usage errors

Exit Codes

All pytest-jux CLI commands use standard exit codes:

Exit Code	Meaning	Description
`0`	Success	Command completed successfully
`1`	General Error	Generic error (file not found, invalid input, etc.)
`2`	Verification Failed	Signature verification failed (tampered report)
`3`	Configuration Error	Invalid configuration or missing required settings

Configuration Errors

CONFIG-001: Private key not found

Error Message:

Error: Private key not found: /path/to/key.pem

Cause: The specified private key file does not exist.

Solution:

Check the path is correct
Verify the file exists: ls -la /path/to/key.pem
Generate a new key if missing: jux-keygen --type rsa --bits 4096 --output key.pem

Command: All signing commands (jux-sign, pytest --jux-key, etc.)

Exit Code: 1

CONFIG-002: Certificate not found

Error Message:

Error: Certificate file not found: /path/to/cert.pem

Cause: The specified certificate file does not exist.

Solution:

Check the path is correct
Verify the file exists: ls -la /path/to/cert.pem
Generate a new certificate: jux-keygen --cert --output key.pem

Command: All signing commands (jux-sign, pytest --jux-cert, etc.)

Exit Code: 1

CONFIG-003: Invalid storage mode

Error Message:

ValidationError: storage_mode must be 'auto' or 'disabled'

Cause: Storage mode set to invalid value.

Solution: Use valid storage mode:

# Valid options
pytest --jux-storage-mode auto
pytest --jux-storage-mode disabled

Command: pytest, jux-config

Exit Code: 3

CONFIG-004: Configuration file not found

Error Message:

Error: Configuration file not found: /path/to/config.toml

Cause: Specified configuration file does not exist.

Solution:

Check the path is correct
Create configuration file: jux-config edit
Use default location: ~/.config/pytest-jux/config.toml

Command: pytest --jux-config, jux-config

Exit Code: 1

CONFIG-005: Invalid TOML syntax

Error Message:

TOMLDecodeError: Invalid TOML syntax at line X

Cause: Configuration file has syntax errors.

Solution:

Validate TOML syntax: https://www.toml-lint.com/
Check for common issues:
- Missing quotes around strings
- Invalid escape sequences
- Mismatched brackets
Edit configuration: jux-config edit

Command: All commands reading configuration

Exit Code: 3

File Errors

FILE-001: Input file not found

Error Message:

Error: Input file not found: /path/to/junit.xml

Cause: The specified input XML file does not exist.

Solution:

Verify the file exists: ls -la /path/to/junit.xml
Check pytest created the file: pytest --junitxml=junit.xml
Verify the path is correct

Command: jux-sign, jux-verify, jux-inspect

Exit Code: 1

FILE-002: Permission denied (read)

Error Message:

PermissionError: Permission denied: /path/to/file

Cause: Insufficient permissions to read file.

Solution:

Check file permissions: ls -la /path/to/file
Grant read permission: chmod 644 /path/to/file
Or run with appropriate user

Command: All commands reading files

Exit Code: 1

FILE-003: Permission denied (write)

Error Message:

PermissionError: Permission denied: /path/to/output

Cause: Insufficient permissions to write file.

Solution:

Check directory permissions: ls -lad /path/to/
Grant write permission: chmod 755 /path/to/
Or use different output directory

Command: All commands writing files

Exit Code: 1

FILE-004: Disk full

Error Message:

OSError: No space left on device

Cause: Insufficient disk space.

Solution:

Check disk space: df -h
Free up space or use different partition
Clean up cache: jux-cache clean --days 30

Command: All commands writing files

Exit Code: 1

Cryptographic Errors

CRYPTO-001: Invalid private key format

Error Message:

ValueError: Invalid private key format

Cause: Private key file is not valid PEM format or is corrupted.

Solution:

Verify key format: openssl rsa -in key.pem -check
Regenerate key: jux-keygen --type rsa --bits 4096 --output key.pem
Ensure file wasn't corrupted during transfer

Command: jux-sign, pytest

Exit Code: 1

CRYPTO-002: Unsupported key type

Error Message:

ValueError: Unsupported key type: DSA

Cause: Key type not supported (only RSA and ECDSA are supported).

Solution: Generate supported key type:

# RSA (recommended)
jux-keygen --type rsa --bits 4096 --output key.pem

# ECDSA
jux-keygen --type ecdsa --curve P-256 --output key.pem

Supported:

✅ RSA (2048, 3072, 4096 bits)
✅ ECDSA (P-256, P-384, P-521)
❌ DSA
❌ Ed25519 (not yet supported)

Command: jux-sign, pytest

Exit Code: 1

CRYPTO-003: Signature verification failed

Error Message:

ValueError: Signature verification failed

Cause: XML was modified after signing (tampered) or signature is invalid.

Solution:

If expected: Report is tampered, reject it
If unexpected:
- Verify using correct certificate
- Check XML wasn't modified
- Re-sign the report

Command: jux-verify

Exit Code: 2 (verification failed)

CRYPTO-004: Certificate expired

Error Message:

ValueError: Certificate has expired

Cause: X.509 certificate validity period has ended.

Solution:

Generate new certificate: jux-keygen --cert --days-valid 365
Or obtain valid certificate from CA
Re-sign reports with new certificate

Command: jux-verify

Exit Code: 2

CRYPTO-005: Certificate does not match signature

Error Message:

ValueError: Certificate does not match signature

Cause: Wrong certificate used for verification (doesn't match private key used for signing).

Solution:

Use matching certificate (public key corresponding to private key used for signing)
Verify certificate fingerprint
Check certificate was not replaced

Command: jux-verify

Exit Code: 2

Validation Errors

VALID-001: Invalid XML syntax

Error Message:

XMLSyntaxError: XML syntax error at line X: <error details>

Cause: Input file is not valid XML.

Solution:

Validate XML syntax: xmllint --noout file.xml
Check for common issues:
- Unclosed tags
- Invalid characters
- Encoding issues
Regenerate report: pytest --junitxml=junit.xml

Command: All commands processing XML

Exit Code: 1

VALID-002: Not a JUnit XML file

Error Message:

ValueError: Not a valid JUnit XML file

Cause: XML file doesn't match JUnit XML schema.

Solution:

Verify file is JUnit XML (should have <testsuite> or <testsuites> root)
Check pytest generated the file correctly
Validate schema: https://github.com/windyroad/JUnit-Schema

Command: All commands expecting JUnit XML

Exit Code: 1

VALID-003: No signature found

Error Message:

ValueError: No signature found in XML

Cause: XML file is not signed (no <Signature> element).

Solution:

Sign the report first: jux-sign -i junit.xml -o signed.xml --key key.pem
Or use signed report for verification

Command: jux-verify

Exit Code: 1

VALID-004: Malformed signature

Error Message:

ValueError: Malformed XMLDSig signature

Cause: Signature element exists but is invalid or corrupted.

Solution:

Re-sign the report: jux-sign -i junit.xml -o signed.xml --key key.pem
Verify signature wasn't corrupted during transfer
Check XML wasn't manually edited

Command: jux-verify

Exit Code: 2

Storage Errors

STORAGE-001: Report not found

Error Message:

StorageError: Report not found: <hash>

Cause: Requested report does not exist in storage.

Solution:

Verify report hash is correct
List available reports: jux-cache list
Check report was stored: Storage may have been purged

Command: jux-cache show

Exit Code: 1

STORAGE-002: Metadata not found

Error Message:

StorageError: Metadata not found: <hash>

Cause: Report exists but metadata file is missing.

Solution:

Report storage is inconsistent
Check metadata file: ~/.local/share/pytest-jux/metadata/<hash>.json
May need to re-generate report

Command: jux-cache show

Exit Code: 1

STORAGE-003: Storage directory not writable

Error Message:

PermissionError: Cannot write to storage directory

Cause: Insufficient permissions for storage directory.

Solution:

Check directory permissions: ls -lad ~/.local/share/pytest-jux/
Create directory: mkdir -p ~/.local/share/pytest-jux/reports
Grant permissions: chmod 755 ~/.local/share/pytest-jux/

Command: All commands storing reports

Exit Code: 1

CLI Errors

CLI-001: Missing required argument

Error Message:

error: the following arguments are required: --key

Cause: Required command-line argument not provided.

Solution: Provide required argument:

# Example: Missing --key
jux-sign -i junit.xml -o signed.xml --key key.pem

Command: All CLI commands

Exit Code: 2 (usage error)

CLI-002: Invalid argument value

Error Message:

error: argument --type: invalid choice: 'dsa' (choose from 'rsa', 'ecdsa')

Cause: Invalid value for argument.

Solution: Use valid value:

# Valid key types
jux-keygen --type rsa --output key.pem
jux-keygen --type ecdsa --output key.pem

Command: All CLI commands

Exit Code: 2 (usage error)

CLI-003: Conflicting arguments

Error Message:

error: argument --input: not allowed with argument <stdin>

Cause: Conflicting command-line arguments provided.

Solution: Use either file input OR stdin, not both:

# File input
jux-sign -i junit.xml -o signed.xml --key key.pem

# Stdin input
cat junit.xml | jux-sign -o signed.xml --key key.pem

Command: Commands accepting stdin

Exit Code: 2 (usage error)

CLI-004: No JUnit XML report found

Error Message:

Error: No JUnit XML report found. Use --junitxml option.

Cause: pytest-jux plugin activated but no --junitxml option specified.

Solution: Add --junitxml to pytest command:

pytest --junitxml=test-results/junit.xml

Or add to pytest.ini:

[pytest]
addopts = --junitxml=test-results/junit.xml

Command: pytest

Exit Code: 1

Error Message Patterns

Pattern: "No such file or directory"

Common Causes:

File path typo
File doesn't exist
Relative vs absolute path confusion

Solution: Use absolute paths or verify working directory

Pattern: "Permission denied"

Common Causes:

Insufficient file permissions
Insufficient directory permissions
File owned by different user

Solution: Check permissions with ls -la, use chmod to fix

Pattern: "Invalid format"

Common Causes:

Wrong file format (e.g., providing certificate when key expected)
Corrupted file
Encoding issues

Solution: Verify file format, regenerate if corrupted

Debugging Tips

Enable Debug Logging

# Enable debug output
export JUX_DEBUG=1
pytest --junitxml=junit.xml --jux-key key.pem

Verbose Output

# pytest verbose
pytest -v --junitxml=junit.xml

# CLI command verbose (where supported)
jux-verify -i signed.xml --cert cert.pem -v

Validate Configuration

# Check current configuration
jux-config show

# Validate configuration
jux-config validate

Check File Permissions

# Check key file permissions
ls -la ~/.ssh/jux/

# Should be 600 for private keys
chmod 600 ~/.ssh/jux/key.pem

Getting Help

If you encounter an error not listed here:

Check GitHub Issues: https://github.com/jux-tools/pytest-jux/issues
Review Documentation: See Troubleshooting Guide
Report Bug: Include error message, command, and pytest-jux version

Collect Debug Information:

# pytest-jux version
pytest --version | grep pytest-jux

# Python version
python --version

# Full error output
pytest --junitxml=junit.xml --jux-key key.pem 2>&1 | tee error.log

FilesExpand file tree

error-codes.md

Latest commit

History

error-codes.md

File metadata and controls

Error Code Reference

Overview

Error Categories

Exit Codes

Configuration Errors

CONFIG-001: Private key not found

CONFIG-002: Certificate not found

CONFIG-003: Invalid storage mode

CONFIG-004: Configuration file not found

CONFIG-005: Invalid TOML syntax

File Errors

FILE-001: Input file not found

FILE-002: Permission denied (read)

FILE-003: Permission denied (write)

FILE-004: Disk full

Cryptographic Errors

CRYPTO-001: Invalid private key format

CRYPTO-002: Unsupported key type

CRYPTO-003: Signature verification failed

CRYPTO-004: Certificate expired

CRYPTO-005: Certificate does not match signature

Validation Errors

VALID-001: Invalid XML syntax

VALID-002: Not a JUnit XML file

VALID-003: No signature found

VALID-004: Malformed signature

Storage Errors

STORAGE-001: Report not found

STORAGE-002: Metadata not found

STORAGE-003: Storage directory not writable

CLI Errors

CLI-001: Missing required argument

CLI-002: Invalid argument value

CLI-003: Conflicting arguments

CLI-004: No JUnit XML report found

Error Message Patterns

Pattern: "No such file or directory"

Pattern: "Permission denied"

Pattern: "Invalid format"

Debugging Tips

Enable Debug Logging

Verbose Output

Validate Configuration

Check File Permissions

Getting Help

See Also