Support playbook

How to help a Flox customer who is stuck: what to ask first, a table of the failures that come up most (with the diagnosis and the docs page that fixes each), what the pricing page says about support, how to file a good issue on flox/flox, and where help lives. Everything here is advice built on cited facts; where the sources do not settle something it is flagged [verify].

This page is drawn from https://github.com/flox/flox-skills/blob/main/flox-plugin/skills/flox-debug/SKILL.md, https://flox.dev/docs/concepts/package-groups, https://flox.dev/docs/man/flox-edit, https://flox.dev/docs/concepts/activation, https://flox.dev/docs/concepts/authentication, https://flox.dev/docs/install-flox/troubleshooting, https://flox.dev/docs/install-flox/install, https://flox.dev/pricing/, https://github.com/flox/flox and https://status.flox.dev/.

Triage order

Work from widest scope to narrowest: service, sign-in, version, environment, platform.

flowchart TD
  A[Customer reports a problem] --> B{Status page shows<br/>an incident?}
  B -- yes --> C[Share the link, advise a retry]
  B -- no --> D{Command resolves packages<br/>and user not signed in?}
  D -- yes --> E[flox auth login or token]
  D -- no --> F{Install or upgrade<br/>of Flox itself?}
  F -- yes --> G[Install logs and previous Nix]
  F -- no --> H{Resolution error?}
  H -- yes --> I[Package groups and options]
  H -- no --> J[Activation, hook, profile, platform]

1. Check https://status.flox.dev/ first. On 2026-10-29 it listed “Degraded catalog response time and increased error rate”, with “A retry should proceed normally.” (https://status.flox.dev/api/v2/incidents.json).
2. Check sign-in. Since 2026-10-20 commands that resolve packages fail without a login, with an error that tells them to run flox auth login (https://flox.dev/docs/concepts/authentication). flox auth status shows the state (https://flox.dev/docs/man/flox-auth).
3. Only then debug the manifest.

The first five questions

Ask all five in one message so the customer answers once. The first mirrors the fields in the repo’s bug template (https://raw.githubusercontent.com/flox/flox/main/.github/ISSUE_TEMPLATE/bug-report.md).

1. Output of flox --version and uname -a.
2. The exact command and the full error, re-run with flox -v for more logging; the verbose flag must come before the subcommand (https://flox.dev/docs/man/flox).
3. Are you signed in (flox auth status), and is this a laptop, CI or an agent sandbox? Tokens need Flox 1.14.0 or newer (https://flox.dev/docs/concepts/authentication).
4. Your .flox/env/manifest.toml and manifest.lock, and whether the environment is local or pushed to FloxHub (https://flox.dev/docs/man/flox-edit).
5. What changed: a new package, a version pin, a new system, or an upgrade of Flox.

Common failures

Package groups: the “too tight” error

The docs reproduce the error and the fix: “resolution failed: constraints for group ‘toplevel’ are too tight”, solved by isolating one package with pkg-group (https://flox.dev/docs/concepts/package-groups). The flox-debug skill warns that this message is generic: “constraints_too_tight is the generic group-level failure and names no cause by itself”, and that the most common cause is page coverage, not a version clash (https://github.com/flox/flox-skills/blob/main/flox-plugin/skills/flox-debug/SKILL.md). Its order is page analysis first, [options] exclusions second, true version conflicts last. Its test is to resolve the existing packages alone, then the new package alone, and compare page ranges (same page). It also says never to narrow systems to the local machine when reproducing (same page).

Upgrade picks an older build

The skill describes a new publish that is not picked up because the new build was evaluated against an old nixpkgs pin, so an older build on a newer base page wins (https://github.com/flox/flox-skills/blob/main/flox-plugin/skills/flox-debug/SKILL.md). Separately, the base catalog docs say a difference between flox show (metadata only) and flox install “may be due to this logic”, meaning the known-good-build checks (https://flox.dev/docs/concepts/base-catalog). Also check stability: a group set to stable “is upgraded at most once per month” (https://flox.dev/docs/man/flox-upgrade).

Managed environments: sync or reset

For environments pushed to or pulled from FloxHub, local changes to the manifest “will block the use of the environment commands” install, uninstall, edit and upgrade (https://flox.dev/docs/man/flox-edit). The two exits: flox edit --sync commits local changes to a new generation, and flox edit --reset discards them and resets to the latest generation (same page). Ask which one they want before running either; --reset loses edits.

Hooks versus profile

hook.on-activate is always Bash and “Can’t use aliases”; [profile] is sourced by the user’s shell, so that is where aliases and functions go (https://flox.dev/docs/concepts/activation). profile.common is sourced by all shells, so avoid non-portable syntax such as export VAR=value there and use profile.bash or profile.zsh instead (same page). The hook runs for the first activation only; later activations apply recorded variables (same page).

Non-interactive shells and CI

flox activate runs in four modes. A subshell, in-place (eval "$(flox activate)") and flox activate -c run both hook and profile; flox activate -- skips [profile] and does not support chained commands or aliases (https://flox.dev/docs/concepts/activation). In scripts, -D/--default “will fail with an error when authentication is missing” (https://flox.dev/docs/man/flox-activate).

Platforms

• WSL 2: “Support for WSL 2 is experimental”; install “will fail on WSL 1”; the nix-daemon must start with the distribution (https://flox.dev/docs/install-flox/install).
• macOS versus Linux: pure builds on macOS “will still have network access” (https://flox.dev/docs/concepts/manifest-builds). Install logs live in /var/log/install.log on macOS and /tmp/flox-installation.log.<timestamp> on Linux (https://flox.dev/docs/install-flox/troubleshooting).
• Systems: when [options] systems is absent, the flox-debug skill says the default is three systems as of Flox 1.15, with x86_64-darwin only if declared (https://github.com/flox/flox-skills/blob/main/flox-plugin/skills/flox-debug/SKILL.md) [verify] against the manifest reference.
• Native Windows: not documented in the sources I read [verify].

Support tiers

The pricing page (https://flox.dev/pricing/) lists:

The homepage adds “Support with an SLA”, described as “A named team, response-time commitments, and a roadmap you can influence” (https://flox.dev/). No response times or hours appear in the sources [verify], so quote none.

Where help lives

The repo README lists Discourse (https://discourse.flox.dev/), Slack (https://go.flox.dev/slack) and GitHub Issues (https://github.com/flox/flox/issues/new/choose) (https://github.com/flox/flox). The authentication docs add email: support@flox.dev (https://flox.dev/docs/concepts/authentication). Security reports go to security@flox.dev (https://github.com/flox/flox). The issue template config links its “Ask a question” button to https://discourse.floxdev.com/ while the README links discourse.flox.dev (https://raw.githubusercontent.com/flox/flox/main/.github/ISSUE_TEMPLATE/config.yml) [verify] which is current.

Filing a good GitHub issue

Templates on flox/flox: Bug report, Install failure and Feature request, and blank issues are enabled (https://raw.githubusercontent.com/flox/flox/main/.github/ISSUE_TEMPLATE/config.yml). The bug template asks for the bug, steps to reproduce, result, expected result, terminal output, the Flox version (from flox --version) and uname -a (https://raw.githubusercontent.com/flox/flox/main/.github/ISSUE_TEMPLATE/bug-report.md). The install-failure template asks for installer logs “redacting anything sensitive”: /tmp/flox-installation.log.$timestamp on Linux, or the com.floxdev.flox lines of /var/log/install.log on macOS (https://raw.githubusercontent.com/flox/flox/main/.github/ISSUE_TEMPLATE/install-failure.md). CONTRIBUTING.md covers building and pull requests, including a CLA, not issue triage (https://github.com/flox/flox/blob/main/CONTRIBUTING.md). The GitHub API shows 461 open issues and pull requests combined on 2026-11-04 (https://api.github.com/repos/flox/flox).

Add to any bug: the manifest, the lockfile, flox auth status, the -v output and the OS. Redact tokens.

Customer reply template

Hi NAME,

Thanks for the detail. From your flox --version (VERSION) and the error ERROR_TEXT, this looks like CAUSE.

The docs describe it at DOCS_URL. Please try: COMMAND.

If it does not clear, reply with flox -v COMMAND output, flox auth status, and your manifest.toml and manifest.lock, and we will look further. Status page: https://status.flox.dev/.

Say what you can see in their output before saying what they should do, and do not promise a root cause until the lockfile has been read.