Troubleshooting

Common issues and solutions for Ninja service management.

Service Won't Start

Check the lock file:

cat ~/.ninja/shurikens/{name}/.ninja/shuriken.lck

Look for PID and start time to verify process state.

Inspect logs:

Check the log path defined in manifest.toml under [logs].log-path.

Test manually:

Run the service binary or script directly to reproduce errors:

cd ~/.ninja/shurikens/{name}
./bin/service --config config.ini

Configuration Not Applied

Verify template exists:

ls ~/.ninja/shurikens/{name}/.ninja/config.tmpl

Check options file:

Ensure all variables in the template are defined in options.toml.

Regenerate configuration:

shurikenctl configure {name}
# Check output at the configured config-path

Installation Issues

Verify permissions:

# Check write access to Ninja directory
ls -ld ~/.ninja/shurikens/

Validate package:

Ensure the .shuriken file matches your platform (linux-x86_64, windows-x86_64, macos-aarch64, or any).

Inconsistent State

Stop and cleanup:

shurikenctl stop {name}

# If process is stuck, manually remove lock file
rm ~/.ninja/shurikens/{name}/.ninja/shuriken.lck

# Verify no processes are running
ps aux | grep {name}

Getting Help

• Enable verbose logging in shuriken management scripts
• Review postinstall scripts for setup issues
• Check the GitHub issues for known problems