Troubleshooting

Find what you're seeing below. Most problems are a setting, and Ferrule's log says which one.

Read the log first

The ferrule container's log says what went wrong, in plain words. It logs only failures and changes, so a quiet log means nothing is wrong.

PortainerDocker Compose

Containers → ferrule → Logs.

docker compose logs --tail 50 ferrule

If the container keeps restarting, the last line is the reason, for example configuration: ADMIN_PASSWORD must be at least 12 characters.

Installing

What you see	Why, and what to do
Portainer: reference not found	The Repository reference is wrong. Use refs/heads/main
Portainer: authentication required	Turn Authentication off. The URL is https://github.com/ferrulehq/ferrule-deploy
The page at :8090 doesn't open	Is the ferrule container running? Is port 8090 used by something else? Is a firewall in the way?
The dashboard opens instead of the setup wizard	The stack already has settings. Use Settings → Run setup again (Changing your setup)
Errors about container names already in use	Another Ferrule stack is on this host (Running beside another stack)

Private beta: not watching

Ferrule is running, but has no license key in force, so it reads nothing. The box says why:

It says	Do this
it needs a license key to run	Enter the key you were sent on Settings → License (Enter your license). It starts watching within a poll
the key has been withdrawn	Ask for a new key on the Ferrule Discord
not confirmed online since a date	Let the Docker host reach https://license.ferrulehq.dev. It starts again at the next check

Ferrule won't start

The log's last line names the setting. The common ones:

The log says	Do this
ADMIN_PASSWORD must be at least 12 characters	Use a longer password. The wizard makes one for you
UNIFI_HOST is required	Set the console's address, or UNIFI_ENABLED=false if you watch only servers and storage
set UNIFI_API_KEY, or UNIFI_USERNAME and UNIFI_PASSWORD	Give it at least one way to sign in to the console
... and no SOURCE_1..SOURCE_8 or CHECKS is set, so there is nothing to watch	With UniFi off, add at least one server or storage system, or an up-check
SETTINGS_KEY or BACKUP_KEY arrived as N characters	The key is damaged or cut short. It's 44 characters, or 43 without the final =. Paste the original back from ferrule.env
LDAP: ldap:// would send passwords unencrypted	Use ldaps://, or set LDAP_STARTTLS=true
Anything about a value that's wrong for no reason you can see	Does the value contain a $? Write each $ as $$ in the stack. The wizard does this for you

Something isn't connecting

These show under Needs attention, and on the source's own tab.

Message	Meaning
The console refused the login / login rejected	The UniFi account is a cloud (ui.com) account, or has MFA on. Make a local account with MFA off (UniFi Network)
Disk health and recorder temperatures need the local admin account	Protect has an API key but no local admin. A separate UNVR needs its own admin, not the gateway's (UniFi Protect)
refused the credentials (401)	Wrong token or password for that server, or the token lacks the read-only role (Connect your gear)
Nothing answered at that address and port	Wrong address or port, or a firewall between the Docker host and that system
That address doesn't resolve	A typo in the hostname, or the Docker host can't resolve it: use the IP address
The certificate isn't trusted	Leave certificate checking off unless the system has a real certificate
can't be browsed for orphaned disks / may not read licenses	vCenter's account needs Browse datastore or Global → Licenses: both read-only (vCenter)
it answers SNMP, but not as a PDU Ferrule reads	The PDU isn't an APC, Raritan or Eaton, or the address is another device (PDUs)
set user= on the slot to the phpIPAM API app's ID	phpIPAM needs the API app's ID as the user (IPAM and DCIM)
snmp: the authentication passphrase arrived as N characters	QNAP passphrases are at least 8 characters. A $ must be written $$, and the authentication passphrase can't contain a colon (QNAP)

Alerts and notifications

What you see	Why, and what to do
No notifications at all	Check Settings → Notifications: the channel should say it's set up. Use its Test button
An alert shows but didn't notify	Alerts notify only after 2 minutes (NOTIFY_DELAY), and only at the levels you chose (critical only, by default). One that clears first sends nothing
Alerts already true when Ferrule started never notified	By design: they weren't new. They still show on the dashboard
Bundled Gotify didn't start	Your Portainer may not pass COMPOSE_PROFILES on. Add it to the stack's variables by hand, with the value from ferrule.env
A flood of alerts during planned work	Start maintenance before the work (Alerts and notifications)
A port warns every night as a slow link	A computer on it probably sleeps. Click It sleeps: ignore 100 Mb/s here on the alert (Switches)

Things that look wrong but aren't

• Coverage below 100% on a new install: Ferrule can only speak for the time it has been watching. A 30-day figure needs 30 days of history.
• "modem says internet: no (ignored: traffic is flowing)": the modem's own flag is often wrong. Ferrule ignores it while a WAN carries traffic.
• A reading marked stale: Ferrule couldn't reach that device on the last poll, so it shows the last good reading rather than nothing.
• Gateway SFP+ ports with no optical readings: many UniFi gateways don't report them (What your hardware won't report).
• License "Waiting for the first check-in": normal for a new key, for up to a couple of hours (Enter your license).
• Capacity says "needs N more days of history": forecasts need three weeks of daily history, and start again after a cluster or datastore changes size (Capacity planning).
• A port shows a dashed outline: it's reserved (Reserving a port).
• An add-host check line says ?: Ferrule couldn't tell, and says why; it never guesses (Adding a host).
• The probe says it's unavailable: the demarcation probe needs a setting the Docker host may not allow. Everything else carries on.

Reporting a problem

If something isn't covered here, or the docs were wrong, please open an issue on GitHub. Include:

1. Your version. It's at the foot of every page, such as Ferrule 0.0.3.
2. What you did, what you expected, and what happened.
3. A diagnostic bundle, if it's about something Ferrule reads (see below). If you can't make one, the ferrule log instead: the last 50 lines or so (docker compose logs --tail 50 ferrule).
4. A screenshot, if it's about the screen.

Making a diagnostic bundle

A diagnostic bundle is one file that shows what your gear sent Ferrule. It lets us fix a problem with hardware or firmware we don't have.

1. Open Settings → Diagnostics. You need to be an admin, or sign-in must be off.
2. Press Make a bundle. Ferrule records what your sources answer for about a minute, long enough for each one to be polled once. Leave the page open until it says Made.
3. Look through the preview, then press Download and attach the file to your issue.

What's in the bundle:

• What each source answered during that minute.
• The last few hundred log lines.
• Your settings, without their secrets.
• Any value Ferrule didn't recognise.

Passwords, API keys, tokens and session cookies are always removed, whatever you choose. Ferrule never records sign-in exchanges or the headers that carry credentials.

By default the bundle is also anonymised:

• device, host and site names, MAC and IP addresses, hostnames, serial numbers and e-mail addresses become placeholders such as name-3, 10.255.0.4 and host-1.example;
• the same value gets the same placeholder throughout, so a pattern still shows.

Tick Keep real names and addresses only if the names matter to the problem.

The What Ferrule understood table above the button is worth a look on its own. It lists every address each source was asked for and what came back last. A row in red, such as a 404 or a time-out, is often the whole answer.

Remove secrets first

Never paste ferrule.env, a password, a token, an API key or a license key into an issue. The log doesn't contain secrets, but check anything you've copied from elsewhere.