Skip to content

FAQ & Troubleshooting

Common issues and solutions when building, installing, and running milk.

1. Installation

CMake cannot find cfitsio 
Could NOT find CFITSIO

Solution: Install the development headers:

## Ubuntu/Debian
sudo apt-get install libcfitsio-dev

## CentOS/RHEL
sudo yum install cfitsio-devel

Or build without cfitsio:

cmake .. -DUSE_CFITSIO=OFF

See Build Tiers and Compile Instructions for details.

Build fails with missing readline/ncurses 
fatal error: readline/readline.h: No such file or directory

Solution: Install the development headers, or build without CLI:

## Install headers
$ sudo apt-get install libreadline-dev libncurses5-dev

## Or build standalone-only (no interactive CLI)
$ cmake .. -DUSE_CLI=OFF
Library not found at runtime 
error while loading shared libraries: libImageStreamIO.so

Solution: Add the install directory to the linker path:

$ echo "/usr/local/lib" > usrlocal.conf
$ sudo mv usrlocal.conf /etc/ld.so.conf.d/
$ sudo ldconfig

Or set LD_LIBRARY_PATH in your shell profile:

export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

2. Shared Memory

See also: Streams

Permission denied when accessing /milk/shm 
Cannot open /milk/shm/stream.im.shm: Permission denied

Solution: Ensure the SHM directory exists and is writable:

$ sudo mkdir -p /milk/shm
$ sudo chmod 1777 /milk/shm

For best performance, mount as tmpfs:

$ echo "tmpfs /milk/shm tmpfs rw,nosuid,nodev" | sudo tee -a /etc/fstab
$ sudo mount /milk/shm
Stale shared memory files

Old .im.shm files from crashed processes can interfere.

Solution:

$ milk-shmimpurge              # remove all stale SHM files
$ milk-shmim-rm <streamname>   # remove a specific stream
SHM directory location

The default shared memory directory is /milk/shm. Override with:

export MILK_SHM_DIR=/path/to/custom/shm

3. FPS / Process Control

See also: FPS · Process Info · FPS Standalone Modes

FPS process won't start — "FPS already exists" 
ERROR: FPS already exists

Solution: Remove the stale FPS, then retry:

$ milk-fps-set <fpsname> ..delete
milk-fpsCTRL shows no processes

Ensure the processinfo SHM directory exists and processes are registered:

$ ls $MILK_SHM_DIR/proc.*.shm   # check for processinfo files
$ milk-procinfo-list             # scan for processes
tmux dispatch not working

If standalone executables launched with -tmux don't appear:

  1. Ensure tmux is installed: which tmux
  2. Check if the tmux session exists: tmux ls
  3. Verify the FPS name has no spaces or special characters.

4. CLI

See also: CLI Reference

milk-cli prompt jumps to bottom of terminal

This can happen when the startup banner clears the screen.

Solution: This is a known cosmetic issue. The prompt will stabilize after the first command.

Command not found — "Unknown command" 
Unknown command: mycommand

Solution: Check that the module is loaded:

milk-cli > m?                      # list all loaded modules
milk-cli > h? mycommand            # search for a command

If the module is a plugin, ensure it was compiled and the .so file is in the library path.

5. Performance

Real-time scheduling

For latency-critical applications (AO loops), configure real-time scheduling:

$ milk-makecsetandrt           # create cpuset, enable RT
$ milk-cli -p 90               # launch with high priority
Semaphore loop speed

Benchmark semaphore performance:

$ milk-semloopspeed

Typical values: >100 kHz on modern hardware.

6. Getting Help

  • CLI help: Type ? or help at the milk-cli > prompt
  • Command help: cmd? <command> for detailed usage
  • Module list: m? to list all loaded modules
  • Documentation: See docs/index.md
  • Issues: Report on GitHub Issues

← Documentation Index