Troubleshooting

Solutions to common issues.

Installation Issues

Command not found

# Check installation
which sireno

# Reinstall
pnpm install -g @sirenodeck/sirenodeck

Permission denied

# Use sudo (not recommended) or fix npm prefix
npm config set prefix ~/.npm-global
export PATH="$PATH:$HOME/.npm-global/bin"

Daemon Issues

Daemon won’t start

# Check status
sireno status

# View logs
sireno logs

# Stop and restart
sireno stop
sireno start

Daemon hangs at startup with no output

At startup Sireno asks each package manager on your PATH — pnpm, npm and yarn — where it keeps its globally installed packages, so that an addon or theme installed globally can be found. A package manager that never answers used to stop startup dead: no log line, no port, no keys lit.

Each of those questions now has a ten-second deadline. A manager that misses it is killed and startup carries on without it, leaving a warning in the log:

sireno logs | grep "did not answer"

Globally installed addons and themes from that manager will not resolve, so fix the manager itself — checking that it answers at all is the quickest test:

pnpm root --global

If the command hangs, or spawns process after process, your package manager install is broken rather than your config. On a slow machine, or the first time Corepack has to prepare a manager, ten seconds can genuinely be too short:

SIRENO_PACKAGE_MANAGER_TIMEOUT_MS=30000 sireno start

These probes never install anything. A manager that is absent, or that declines to answer, is skipped in silence — only the deadline is reported.

Port already in use

# Check what's using the port
lsof -i :3939

# Kill the process
kill <PID>

“another sirenodeck daemon is already running”

Only one daemon may run at a time. It holds a lock socket in its runtime directory for as long as it lives, and a second daemon refuses to start rather than fight it for the ports:

another sirenodeck daemon is already running (pid 4242) — stop it with `sireno stop`

The lock belongs to the kernel, not to a file Sireno maintains, so it is released the moment the holder dies — including a kill -9, a crash or a power cut. A leftover lock socket from a daemon that died is detected and cleared on the next start; there is no stale-lock timeout to wait out.

If the message names a pid that is genuinely gone, that is worth reporting. Check first, since the usual explanation is a daemon you forgot was running:

sireno status
ps -p <pid>

Until this lock existed, a second daemon could start beside the first whenever the pid file went missing or a liveness check misread a running daemon as dead. Both then bound the same ports, each reaped the other’s children, and the deck behaved as though it were fighting itself — because it was.

Sireno says a port is held by “a process that is NOT a sirenodeck child”

On macOS this used to be reported for Sireno’s own frontend, because the checks that identify our processes read /proc, which macOS does not have. Every check therefore answered “not ours” and startup left its own orphans running. They now fall back to ps.

If you still see this message, the holder really is someone else’s, and Sireno deliberately leaves it alone. Find out whose it is before killing anything:

lsof -nP -iTCP:5180 -sTCP:LISTEN

Daemon crashes on startup

# Run in foreground for debugging
sireno run --verbose

Configuration Issues

Config not found

# Check config discovery
sireno run --config /path/to/config.yml

Invalid config

# Validate YAML syntax
# Sireno will show validation errors on startup

Device Issues

No device found

• Ensure Stream Deck is connected
• Try a different USB port
• Use --emulator for testing

Device not responding

# Restart the daemon
sireno restart

Emulator Issues

Emulator won’t load

# Check ports
lsof -i :52938

# Clear cache
rm -rf ~/.cache/sireno-deck

Addon Issues

Addon not loading

• Check addon path is correct
• Verify sirenodeck.json exists
• Check for missing dependencies

Addon causing crashes

# Disable addon in config
# Restart daemon

Performance Issues

Slow response

• Check system resources
• Reduce number of active pollers
• Simplify button configurations

High CPU usage

• Check addon poll intervals
• Review system-status metrics
• Disable unused addons

Getting Help

• Check GitHub Issues
• Enable verbose logging: sireno run --verbose
• Collect logs: sireno logs > debug.log