Troubleshooting

Start with the Setup Tool Console action for the affected container. Logs usually identify the failing layer.

Connection failed

Check:

• The host is reachable and SSH port 22 is open.
• Username/password login works from another SSH client.
• Store password is enabled for password-based authentication.
• The target reports Debian, Raspbian, or Ubuntu in /etc/*release.
• The architecture is x86_64, aarch64, armv7l, or armv6l.

The current Setup Tool does not use SSH private keys.

Container list is empty or reports an error

On the controller, verify:

docker ps -a
curl --unix-socket /var/run/docker.sock http://localhost/containers/json?all=true

If these require sudo, add the SSH user to the Docker group and reconnect. Also confirm curl is installed and Docker is running.

Upload images cannot find a tar file

Keep BFC.SetupTool.exe near the extracted images directory. Confirm that both Gateway and Console tar files exist for the detected architecture. The bundle has no 32-bit Intel image.

If upload finishes but an old container still runs old code, stop and recreate that container. Loading an image does not modify existing containers.

Gateway is unhealthy

1. Confirm bfc-mariadb is running.
2. Open logs for bfc-mariadb and bfc-gateway.
3. Wait for first-time MariaDB initialization.
4. Check whether ports 3306, 5000, or 5001 are already in use.
5. Confirm both containers are attached to bfc-network.

The Gateway retries database server detection and applies migrations at startup.

Script upload says invalid directory system

The selected file must be below a folder named exactly _volumes. Select a .lua file from the release _volumes/__lua_scripts tree or from a copy that preserves that root folder.

Lua container exits or restarts

Review its log for:

• Incorrect device IP addresses or credentials.
• Missing generated plugin DLLs under _volumes/_plugins.
• A source/key type conflict in the Gateway.
• Use of localhost instead of bfc-gateway.
• Missing loop delay.
• Syntax or lifecycle function errors.

Test with examples/hello-world.lua to separate runtime problems from device communication problems.

Node-RED node is missing

Restart bfc-nodered and inspect its logs. Run Setup Node-RED again to reinstall the local package into the persistent data volume. Confirm files/node-red-bfc-gateway.tgz exists beside the Setup Tool bundle and that the controller can reach the npm registry for the dashboard dependency.

Node-RED shows API error

Check:

• Protocol HTTP, host bfc-gateway, port 5000 for the standard Docker setup.
• Gateway credentials.
• Exact source/key spelling and data type.
• That the publishing Lua script is running.
• Both containers are on bfc-network.

A missing value, wrong type, expired/invalid login, or unreachable Gateway all appear as API errors; use Node-RED and Gateway logs for the precise HTTP failure.

Port already allocated

The Setup Tool uses fixed host ports. Stop the conflicting service or container before setup. Current UI commissioning does not provide alternate port fields.