Workflow Issues

Missing Workflow Context

Problem: Workflow requires context (issue ID or PR ID) but it’s not set.

Error Message:

❌ Error: Missing workflow context: Issue ID required for 'backlog' operations

❌ Error: Issue ID required for 'issue' operations
       Set via:
       1. Environment variable: export NIA_ISSUE_ID=<number>
       2. Context file: .nia/context.toml

❌ Error: Pull Request ID required for 'pr' operations
       Set via:
       1. Environment variable: export NIA_PR_ID=<number>
       2. Context file: .nia/context.toml

Cause: Workflow operations on issues/PRs require context IDs, which can be set via environment variables or context file.

Solution:

Set environment variable (temporary):

# For issue workflows
export NIA_ISSUE_ID=123
nia backlog task create

# For PR workflows
export NIA_PR_ID=456
nia pr review

# For workflows requiring both
export NIA_ISSUE_ID=123
export NIA_PR_ID=456
nia pr implement

Set in context file (persistent):

# Create context file
mkdir -p .nia
cat > .nia/context.toml << 'EOF'
issue_id = 123
pr_id = 456
EOF

Verify context is set:

# Environment variables take precedence
echo $NIA_ISSUE_ID
echo $NIA_PR_ID

# Check context file
cat .nia/context.toml

Add to shell profile (for frequently used issue):

# Add to ~/.bashrc or ~/.zshrc
echo 'export NIA_ISSUE_ID=123' >> ~/.bashrc
source ~/.bashrc

Use command-line flags (if supported in future versions):

# Future syntax (not yet implemented)
nia backlog task create --issue 123

Prevention:

Set NIA_ISSUE_ID when starting work on an issue
Create .nia/context.toml for long-running work
Add context to shell profile for active sprints
Document context requirements in team workflows

Invalid Workflow Context

Problem: Context values are invalid (non-numeric, zero, negative).

Error Message:

❌ Error: NIA_ISSUE_ID must be greater than 0

❌ Error: Invalid context: NIA_PR_ID must be a positive number

Cause: Context environment variables contain invalid values.

Solution:

Check current values:

echo "Issue ID: $NIA_ISSUE_ID"
echo "PR ID: $NIA_PR_ID"

Fix invalid values:

# ❌ Wrong - non-numeric
export NIA_ISSUE_ID=abc

# ❌ Wrong - zero
export NIA_ISSUE_ID=0

# ❌ Wrong - negative
export NIA_ISSUE_ID=-1

# ✅ Correct - positive integer
export NIA_ISSUE_ID=123

Clear invalid environment variables:
```
unset NIA_ISSUE_ID
unset NIA_PR_ID
```

Fix context file (if using):

# .nia/context.toml
issue_id = 123  # Must be positive integer
pr_id = 456     # Must be positive integer

Validate and retry:

export NIA_ISSUE_ID=123
nia backlog task create

Prevention:

Always use positive integers for IDs
Validate environment variables in setup scripts
Use context file to avoid typos

Related: Workflow Commands

Command Not Found Errors

Problem: Referenced command or workflow doesn’t exist.

Error Message:

❌ Error: Command not found: plan-create

❌ Error: Workflow not found: plan task create

Cause:

Typo in command name
Custom command not defined
Workflow namespace doesn’t exist

Solution:

List available commands:

nia --help
nia issue --help
nia backlog --help

Check command spelling:

# ❌ Wrong
nia issues draft     # "issues" is plural

# ✅ Correct
nia issue draft      # "issue" is singular

List all workflows:

nia status --verbose
# Shows registered workflows

Check for custom workflows:

cat .nia/config/commands.toml
ls .nia/config/workflows.d/

Verify command exists in documentation:

# Check command reference
cat user-docs/src/reference/commands.md

Use correct namespace hierarchy:

# Commands follow: nia <target> <object> <action>
nia issue plan    # Correct hierarchy
nia issue draft         # Correct hierarchy
nia pr review           # Correct hierarchy

Prevention:

Use tab completion (install with nia completions install)
Reference documentation for exact command names
Test custom workflows after creation

Related: Command Structure, Workflow Commands

Workflow Execution Failures

Problem: Workflow starts but fails during execution.

Error Message:

❌ Error: Workflow execution failed
Agent returned invalid response: {...}

❌ Error: Failed to execute workflow step: plan.task.create

Cause:

Agent execution error
Invalid prompt template
Missing required files
Network timeout
Agent returned unparseable output

Solution:

Check execution logs:

# Find latest job
ls -lt .nia/work/ | head -5

# View logs
cat .nia/work/job_<job_id>/logs/*.log

Review agent trace:

nia trace list
nia trace view <trace-file>

Look for specific errors:
- Prompt not found: Export or create missing prompt
- Agent auth failed: Re-authenticate agent
- Network timeout: Check connectivity, retry
- Invalid response: Check agent output in trace

Test agent directly:

# Test with simple prompt
echo "What is Rust?" | copilot -p

Verify prompt templates exist:

ls .nia/prompts/

# Export default prompts if missing
nia config export --target plan

Check workflow configuration:

cat .nia/config/commands.toml
# Verify task_prompt paths are correct

Enable debug logging:

# Linux/macOS
RUST_LOG=debug nia issue plan

# Windows PowerShell
$env:RUST_LOG="debug"; nia issue plan

Retry with simplified context:

# Try without environment context
unset NIA_ISSUE_ID
nia issue plan

Prevention:

Regularly test workflows after configuration changes
Keep agent updated
Monitor traces for patterns
Validate prompt templates before use

Workflow Doesn’t Execute

Problem: Command runs but nothing visible happens.

Symptom: Command completes without errors but produces no output or results

Cause:

Silent failure in workflow execution
Agent not responding
Output being suppressed
Prompt compilation issues

Solution:

Enable debug logging:

# Linux/macOS
RUST_LOG=debug nia issue draft

# Windows PowerShell
$env:RUST_LOG="debug"; nia issue draft

Check work directory logs:

# Find latest job
ls -lt .nia/work/ | head -5

# Check system log
cat .nia/work/job_*/logs/system.log

Inspect execution traces:

# List available traces
ls .nia/work/job_*/traces/

# View trace file
cat .nia/work/job_*/traces/*.trace.md

Verify AI backend is accessible:

# Test network connectivity to AI service
ping api.github.com  # For GitHub Copilot

Check prompts are loading correctly:

# Use --print-prompt flag to see composed prompt
nia issue draft --print-prompt

Verify workflow configuration:
```
nia config validate
```

Prevention:

Always check logs after execution
Monitor trace files for debugging
Test with –print-prompt first
Ensure AI service credentials are valid

Related: Workflow Commands, Debug Logging

Prompt File Not Found

Problem: Workflow references a prompt file that doesn’t exist.

Error Message:

❌ Error: Prompt file not found: .nia/prompts/my_role.role.md

Cause:

Prompt file doesn’t exist
Typo in TOML configuration
Incorrect prompt file path

Solution:

Check if file exists:
```
ls .nia/prompts/my_role.role.md
```

Create the missing prompt file:

mkdir -p .nia/prompts
cat > .nia/prompts/my_role.role.md << 'EOF'
# Role Prompt
You are an expert software engineer...
EOF

Fix typo in configuration:

# In .nia/config/commands.toml
[workflows.operations.prompts]
role = "my_role"  # Check spelling matches filename

Use built-in prompt instead:

# Export default prompts
nia config export --target issue

Verify prompt file paths:

# List all prompt files
find .nia/prompts -name "*.md"

Prevention:

Use consistent naming for prompt files
Test configuration after adding custom prompts
Keep prompt files in version control
Use nia config export to get default prompts

Missing Workflow Outputs

Problem: Workflow completes successfully but expected output files are missing.

Error Message:

⚠ 4 of 5 expected outputs created

Cause:

AI agents are non-deterministic and may not always create every expected file
Agent misunderstood requirements
File creation failed silently
Output requirements unclear in prompt

Solution:

Use manual retry with default prompt:

# Retry with automatic missing files list
nia code create --retry

Retry with specific instructions:

# Provide guidance for what's missing
nia issue plan --retry "The phase_3.md file needs more detail on testing strategy"

Use automatic retry on initial execution:

# Automatically retry once if outputs are missing
nia code create --auto-retry

Check what’s missing:

# View expected outputs from prompt
nia code create --print-prompt | grep -A 20 "output_requirements"

# Compare with actual files created
ls -la .nia/work/job_*/code/

Manually create missing files then continue work:

# Create placeholder
touch .nia/work/job_123/code/missing_file.md

# Continue with next operation
nia code review

When to use each approach:

--retry (manual): When you want control and can provide specific guidance
--retry "message": When you know what’s wrong and want to tell the agent
--auto-retry: In CI/CD or batch workflows for hands-off resilience

Understanding retry behavior:

Retry continues the same session (preserves conversation context)
Lists specific missing file paths in prompt
Works on all workflow commands with output requirements
Cannot combine with --clear (needs session context)

Prevention:

Use --auto-retry for resilient workflows
Review output requirements before execution
Keep prompts clear and explicit about required files
Use --print-prompt to verify what’s expected

Keyboard shortcuts

Nia CLI User Guide