Skip to main content

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
  1. 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
  1. Validate the config shape:
  • every service needs a non-empty cmd
  • every dependsOn target must exist
  • remove unknown fields
  1. If session API is enabled, validate the bind:
flowlayer-server -c ./flowlayer.jsonc -s 127.0.0.1:6999 -token dev-token

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

  2. 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.