MicroB2B does not start

This page helps when MicroB2B stops at startup, when a change you made does not take effect, and when the database or the payload storage fails. Each heading is what you see. Below it are the likely causes and what to do.

MicroB2B checks its whole configuration at startup. It reports every problem at once, each naming its environment variable, and then exits. The reason is the last thing in the log. With systemd, read it with journalctl -u <your service name>.

Startup stops with authentication: PUBLIC_URL: required

The message may also say SESSION_KEY: required (or SESSION_KEY_FILE). MicroB2B always signs users in. It needs the address users reach it at and a key for the sign-in cookies.

• Set PUBLIC_URL and SESSION_KEY (or SESSION_KEY_FILE).
• PUBLIC_URL must be https:// with no path. Plain http:// works only for localhost, 127.0.0.1 and ::1.

See Required settings.

Startup stops with no secrets key is configured

SECRETS_KEY or SECRETS_KEY_FILE is missing. Set exactly one of them. The key is 32 random bytes in base64 or hex. Make one with openssl rand -base64 32. See Secrets.

If the message says must decode to exactly 32 random bytes, the value is not a valid key. Check for a missing character or extra spaces.

Startup stops with the database is sealed under another secrets key than SECRETS_KEY

The database was set up with a different SECRETS_KEY. Use the key the database was set up with.

If you are rotating the key, put the old key in SECRETS_PREVIOUS_KEYS. If the message says stored secrets are sealed with keys this process does not have, add the keys it names to SECRETS_PREVIOUS_KEYS. See Secrets.

If you lost the key, the stored private keys and passwords cannot be opened. Restore the key from your backup.

Startup stops with configuration validation failed

An environment variable has a value MicroB2B does not accept. The message names it:

A negative pool value, or DB_MAX_IDLE_CONNS above DB_MAX_OPEN_CONNS, is also refused. See Environment variables.

Startup stops with failed to initialize database ... failed to connect to db

MicroB2B cannot reach the database in DB_URL, or the URL is wrong.

• For PostgreSQL, check the host, port, user, password, database name and sslmode.
• Test the connection from the same machine, for example with psql "<your DB_URL>".

See Database.

Startup stops with sqlite journal mode is ... after requesting "wal"

The SQLite file is on a file system that cannot do WAL mode, such as some network mounts. Move the database file to a local disk.

Startup stops with failed to initialize payload storage

MicroB2B could not set up the storage for message contents. Usually it could not read its settings from the database, because the database is not reachable. Fix the database first.

Startup stops with bind: address already in use

The full message is like failed to start apiserver plugin: listen tcp :8080: bind: address already in use. Another program already uses HTTP_PORT.

• Find it with ss -ltnp | grep 8080.
• Stop that program, or set HTTP_PORT to a free port.

The log says AS2 receiver HTTP server error ... address already in use

An AS2 receiver’s port is taken, by another program or by the web UI’s port. MicroB2B keeps running without that receiver.

1. Open the receiver under Plugins > AS2 Receivers and choose a free Port.
2. Restart the receiver on System > Services.

Check the log each time you change a receiver’s port. See AS2 receiver.

A change does not take effect

A new or changed plugin instance does nothing. A plugin instance reads its settings when it starts. Restart it on System > Services. A disabled instance never runs.

A changed global setting does nothing. System > Settings is read when MicroB2B starts. The page says when the saved settings differ from the ones in use. Restart MicroB2B. See Settings.

These take effect at once, without a restart: organizations, partners, AS2 profiles, certificates and routes. A route applies to the next message only. A message that was already routed, or ended Not routed, keeps what it has. Use Redispatch on its page. See Message actions.

A form is refused

The message names the field. Common ones:

• Source Plugin: "x" is not available: no enabled plugin instance has that name.
• redundant with route N (...): one covers the other, so the target would receive every message twice: another route with the same source and target already covers it. Delete or narrow one. See Routes.
• Messages to this partner are encrypted to the partner's certificate, but none is chosen.: choose a Partner Certificate, or set the Encryption Algorithm to None.
• is required unless Delete After Send is set: a file poller needs a Processed Directory, or Delete After Send.

Routes use the names of organizations and partners, or Any. They never use AS2 IDs.

Database problems

database is locked (SQLite). Another program holds a lock on the database file for more than 5 seconds. Close any sqlite3 session on the file. Only MicroB2B should use the file while it runs.

PostgreSQL refuses connections because its limit is reached. Lower DB_MAX_OPEN_CONNS, or raise the server’s max_connections.

Startup fails while creating the tables. The log shows the statement that failed. MicroB2B creates missing tables but never changes existing ones. A database from a different version may need to be replaced. See Upgrading.

Storage problems

Start with Test storage on System > Settings. It stores, reads back and deletes a test file. It tells you which step failed and why.

Local storage. The error comes from the operating system, such as permission denied or no space left on device. Check that the MicroB2B user owns the storage directory and that the disk has room.

S3 storage. The errors are failed to store blob to S3, failed to retrieve blob from S3 or failed to read blob data from S3, followed by the cause:

the message has no "x" payload (it has: ...). The database and the stored files do not match. This happens when one was restored or copied without the other. Always back up and restore both together. See Backup and Payload storage.