Node-RED Login Failed: Fix the Space, Not Image 3.1.1

Login succeeds after regenerating the bcrypt hash with the required space before the password argument, placing that hash in settings.js, and restarting the IOT2040. Image 3.1.1 does not require a different authentication method. The immediate fault is command syntax: without a blank between the closing quote and the password, the shell does not pass the password as process.argv[1].

Symptom Interpretation

Separate a hash-generation error from a Node-RED credential rejection. They occur at different points and require different corrections.

Password-Hash Mechanism

The term hash here means a one-way bcrypt representation of the password. Node-RED stores that representation in settings.js; it does not need the clear-text password in the configuration. At login, the authentication code hashes and compares the submitted password against the stored bcrypt value.

The supplied command runs JavaScript through Node.js:

node -e "console.log(require('bcrypt').hashSync(process.argv[1], 8));" your-password

The quoted text is the program passed to node -e. The blank after the closing double quote terminates that program token. The following token, your-password, becomes the first user argument and is read as process.argv[1]. Omitting the blank joins the JavaScript text and password into one shell token, so the program no longer receives the intended password argument.

The value 8 is the bcrypt work-factor argument used by this command. Preserve it when reproducing the documented procedure. Copy the entire generated hash exactly; bcrypt hashes are case-sensitive, and one missing or substituted character prevents a match.

Hash Generation Procedure

1. Open a shell on the IOT2040 and change to the directory containing the required Node.js bcrypt module:

   cd /usr/lib/node/node-red

2. Run the hash command, replacing your-password with the intended password:

   node -e "console.log(require('bcrypt').hashSync(process.argv[1], 8));" your-password

   Keep one blank between the final double quote and the password. The expected output is a single bcrypt hash string. Do not place the clear-text password in settings.js.

3. Copy the complete generated hash without adding spaces, quotation marks, or line breaks.
4. Change to the Node-RED user directory:

   cd /home/root/.node-red

5. Open the configuration file:

   nano settings.js

If the password contains characters interpreted by the active shell, shell parsing can change the argument before Node.js receives it. Verify the generated hash with an actual login before treating the configuration as complete.

Authentication Configuration

Locate the existing adminAuth example in settings.js. Remove its comment markers and enter the selected username and the generated hash:

adminAuth: {
    type: "credentials",
    users: [{
        username: "<username>",
        password: "<hash-code>",
        permissions: "*"
    }]
},

type: "credentials" selects credential-based authentication. The users array contains the account definition, while permissions: "*" grants that account the configured full permission set. Replace both placeholders; literal angle-bracket text is not a working account.

Preserve the surrounding JavaScript object structure. A comma may be required between adjacent properties, but an extra comma or unmatched brace in the wrong location can stop the settings file from loading. Save the file, then restart the IOT2040 so the running Node-RED instance reads the new authentication configuration.

Numbered Verification Checks

1. Check 1: hash-command output. Expect one generated bcrypt hash after running the command. A JavaScript error, missing output, or output unrelated to a hash points back to command syntax or module loading.
2. Check 2: argument separation. Expect a visible blank between ;" and the password in the command. Without that delimiter, process.argv[1] does not contain the intended password.
3. Check 3: active configuration. Expect adminAuth, type, users, username, password, and permissions to be active JavaScript rather than commented example text.
4. Check 4: post-restart prompt. Expect Node-RED to request a username and password after the IOT2040 restarts. No prompt means the running instance did not apply the intended authentication block.
5. Check 5: credential behavior. Expect the configured username and original clear-text password to permit access. Also submit an intentionally wrong password and expect rejection; this confirms authentication is active rather than bypassed by an existing session.

Recurring Configuration Pitfalls

FAQ