Server Won't Start

Symptoms

• flowlayer-server exits immediately.
• You see a usage error before any service starts.
• No startup plan is printed.

Likely causes

• config path is wrong
• both -c and --config were passed
• too many positional arguments were passed
• config contains unknown or invalid fields
• at least one service has missing or invalid cmd
• dependency graph is invalid (cycle or unknown dependency)
• -s bind address is invalid or already in use

Resolution

1. Start with the simplest valid command:

flowlayer-server -c ./flowlayer.jsonc

2. If the file path is correct, ensure you are not mixing config selectors:

• use -c <path> or --config <path>, not both
• or pass one positional config path

3. Validate the config shape:

• every service needs a non-empty cmd
• every dependsOn target must exist
• remove unknown fields

4. If session API is enabled, validate the bind:

flowlayer-server -c ./flowlayer.jsonc -s 127.0.0.1:6999 -token dev-token

5. If startup fails with dependency errors, check Dependency Cycle.

6. If startup reaches runtime but clients fail, check TUI Cannot Connect.

Fast checks

• config file not found means the selected file path is wrong.
• use either -c or --config, not both means flag conflict.
• too many positional arguments means more than one loose path was passed.
• dependency cycle detected among services means graph planning failed before runtime.