Knowledge base

PMTA knowledge base›File§ 4.2.1

Where the node writes why it did not start

pmta-startuperr.log

It exists because the main log may be unavailable

A separate file for exactly one case: the engine did not start.

Why it is needed at all. A startup failure can be caused by the engine being unable to open the regular log — and it still has to report that. So the message has to go somewhere that does not depend on the configuration being correct.

It is read first on two occasions: right after installation and right after a configuration edit. The manual explicitly names these two cases as typical.

If the file is missing or holds nothing coherent, the manual suggests running the engine in debug mode right in the console — then the message is printed to the screen instead of a file.

⚠️ The manual is inconsistent about the location on Unix. The section on startup failures names the file pmta-startuperr.log, but gives its Unix path as /var/log/pmta/log — that is, the path of the main log itself, even though a paragraph earlier the file is called separate. Where it actually lives is worth checking on the node rather than inferring from the manual.

The main trap is looking for the cause of a startup failure in the main log. It may not exist at all: if the engine could not open it, not a single line will appear there, and the empty log will be taken for the absence of errors. You need to look at this file, and if it is missing, run the engine in the console and read the output.

What the Hub does. It does not read this file. It sees a startup failure indirectly: the node stops responding to telemetry polling, and in the cabinet this looks like an unavailable node — without a cause.

The cause stays on the node, in this file. So on a startup failure after applying a configuration from the Hub, you have to go to the node by hand — telemetry will only say that there is no connection.

What softens this is that the Hub checks configuration parsing before applying and applies it with a reload rather than a restart: an unsuccessful edit leaves the node running on the previous settings (config-reload).

Recommended values

The order for investigating a startup failure:

Step	What to look at
first	this file — the startup failure message
second	the main log, if it exists and something managed to get written to it
third	a run in debug mode in the console, output to the screen

An empty main log proves nothing. It may not have opened at all — exactly the case the separate file exists for.

Check the location on the spot. The manual contradicts itself here, and it is more reliable to find the file by searching the log directory than to follow the stated path.

The investigation order is ours. From the manual here come the file’s purpose, the two typical startup failure cases and the suggestion to run the engine in debug mode; the discrepancy in the Unix path is an observation from the manual’s text.

Example configuration

# startup failure: three places in order
ls -l /var/log/pmta/ && cat /var/log/pmta/pmta-startuperr.logtail -n 50 /var/log/pmta/log
pmtad --debug

The highlighted line first shows what is in the log directory at all — because of the inconsistency in the manual, looking is more reliable than following the named path. The bottom one prints the message right to the screen when there are no files.

yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.

▲

Common mistakes and problems

what people get wrong and how it ends3 mistakes▶

Taking an empty main log as proof that there are no errors

§ 4.2.1

What it costsIt may not have opened at all — this is exactly the case the separate file exists for. Emptiness means not “no errors” but “there was nowhere to write.”

How to spot itThe engine does not start, and there is nothing new in the main log.

How to do it rightRead the startup failure file, and if it is missing, run the engine in debug mode and look at the output on screen.

Following the path from the manual without finding the file

§ 4.2.1

What it costsThe manual calls the file separate but gives the Unix path of the main log. Searching at the stated path may turn up nothing, and the wrong conclusion is drawn that the file does not exist at all.

How to spot itThe named path holds the regular log, and the startup failure file is nowhere to be seen.

How to do it rightLook at the whole log directory, sorted by modification time. Check the location on your own installation.

Expecting the cause of a startup failure from telemetry

§ 4.2.1

What it costsA node that did not start stops responding to polling, and from outside this looks like unavailability — without a cause. The message stays on the node, in the file.

How to spot itIn the cabinet the node is unavailable, and there are no errors in any view.

How to do it rightGo to the node and read the file. Telemetry will only say that there is no connection.

Compatibility

PowerMTA 6.0

described in the manual of this version · platform: any

The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.

Reference data

Syntax: Line-oriented text; a timestamp followed by the startup error.

Everything here comes from the manual, with the section.

Inheritance

The file has no inheritance. Nor is it controlled by settings — that is the whole point: it has to work when the configuration is wrong. The rotation and destination of the regular log do not apply to it.

⇄

Related entries

3 relations

Depends on

The node's main configuration fileA startup failure is most often caused by an edit of exactly this file. § 4.2.1

Works together with

The node's own logSeparated on purpose: a startup failure is precisely the reason nothing will get into the main log anymore. § 4.2.1

Where you can see it

Investigating a startup failureThe investigation that starts with this file. § 4.2.1

Referenced from

Starting in the console with output to the screenThe same thing by another path — for when there is nowhere to write the message. § 4.2.1 LogsThe file this output refers to. inference Configuration parse checkWhat this check does not catch ends up later in the startup failure file. § 4.2.1

How to check on the node

A startup failure investigation starts with the log directory, not with the named path:

ls -lt /var/log/pmta/ | head
pmtad --debug

The first will show which files exist and which one changed last — the timestamp immediately shows whether the engine wrote anything during the startup attempt. The second runs it in the console: the message will appear on screen even if there is nowhere to write it.

◇

What else to read

3 articles

◇Third-party components of the enginePowerMTA runs on five third-party libraries — PCRE, OpenSSL, ICU, gumbo-parser and prometheus-cpp; their behavior is determined by the engine build.◇Accept, route, deliverA message’s path inside the node: accept, decide where, deliver — and all the settings live between these three steps.◇The activation key is a prerequisite for installation, not a step after itWithout an activation key from SparkPost support the engine neither installs nor runs, and the license tier sets the outbound connection ceiling: on Standard everything above 200 is ignored.

In the Hub

Cost of a mistake: safe: a wrong value breaks nothing
Scenarios: Configuration lifecycle · Prepare a node for sending