Problems building with --without-ssl and openssl-related options in NODE_OPTIONS

@joyeecheung

Just opening this to not forget.

There are a handful of command line arguments (like --use-openssl-ca) that are only defined when Node.js is being built with openssl enabled. These CLI flags, however, are allowed in NODE_OPTIONS which may be set generally for a user. When NODE_OPTIONS=--use-openssl-ca and we ./configure --without-ssl, the build will fail with an obscure and unhelpful error in the node_mksnapshot step:

FAILED: gen/node_snapshot.cc 
cd ../../; /home/jsnell/projects/node/node/out/Release/node_mksnapshot /home/jsnell/projects/node/node/out/Release/gen/node_snapshot.cc

  #  /home/jsnell/projects/node/node/out/Release/node_mksnapshot[675255]: int BuildSnapshot(int, char **) at ../../tools/snapshot/node_mksnapshot.cc:69
  #  Assertion failed: !result->early_return()

----- Native stack trace -----

 1: 0x5bb18fce856a node::Assert(node::AssertionInfo const&) [/home/jsnell/projects/node/node/out/Release/node_mksnapshot]
 2: 0x5bb18ff5f423 BuildSnapshot(int, char**) [/home/jsnell/projects/node/node/out/Release/node_mksnapshot]
 3: 0x735750429d90  [/lib/x86_64-linux-gnu/libc.so.6]
 4: 0x735750429e40 __libc_start_main [/lib/x86_64-linux-gnu/libc.so.6]
 5: 0x5bb18fd2ef05 _start [/home/jsnell/projects/node/node/out/Release/node_mksnapshot]
Aborted (core dumped)
ninja: build stopped: subcommand failed.
make: *** [Makefile:151: node] Error 1

It's probably a good idea to have node_mksnapshot either ignore NODE_OPTIONS or print more helpful error messages; or, alternatively, allow openssl-related options like --use-openssl-ca to be a defined non-op when building with --without-ssl

/cc @joyeecheung

I think it makes sense to just copy the handling from

node/src/node.cc

Lines 1494 to 1499 in 0bbe7c3

    
           for (const std::string& error : result->errors()) { 
        
             FPrintF(stderr, "%s: %s\n", result->args().at(0), error); 
        
           } 
        
           if (result->early_return()) { 
        
             return result->exit_code_enum(); 
        
           }

over to

node/tools/snapshot/node_mksnapshot.cc

Lines 69 to 70 in c5cfdd4

    
           CHECK(!result->early_return()); 
        
           CHECK_EQ(result->exit_code(), 0);

Well, that would certainly help but that output still is rather obscure. I think there are several things that would be significant improvements. For one, much of the code around this area is almost entirely undocumented. It's extremely difficult to know what it happening in here and what failure conditions may apply. Failures in the node_mksnapshot process are extremely difficult to debug. Even some basic explanations in the code about what the possible failure conditions are would be helpful, so I think when I'm able to I'll come back and try to add some documentation.

But just in general it is counter-intuitive that the NODE_OPTIONS env var would impact the build of node itself. Would there be any issues with enabling the kDisableNodeOptionsEnv flag when initializing the platform in node_mksnapshot?

PR: #59437

For one, much of the code around this area is almost entirely undocumented.

Are you looking for https://github.com/nodejs/node/blob/main/tools/snapshot/README.md?

Would there be any issues with enabling the kDisableNodeOptionsEnv flag when initializing the platform in node_mksnapshot?

If this gets serializad into/accessed JS land in anyway, it will be. For example, if the custom snapshot is used and the snapshot script uses the runtime options, or checks https://nodejs.org/api/process.html#processallowednodeenvironmentflags

From #59437, it doesn't look like a bug, more like a DX issue - node_mksnapshot could've printed the errors then exiting more gracefully instead of just asserting and crashing, but since it's a build tool, asserting is also correct, just that the DX is less nice.

As for the documentation, there's already one in https://github.com/nodejs/node/blob/main/tools/snapshot/README.md - not sure how to make that more visible to people looking for documentation, over the last collaboration summit some people suggested to use LLM tools to deal with the "there might have been a documentation, but I don't know how to find it" problem. If you are looking for specific debugging commands, this was documented in src/README.md.

node/src/README.md

Line 531 in 4eeb78b

$ lldb -- out/Release/node_mksnapshot out/Release/gen/node_snapshot.cc

I suggest using this command to look for the documentation, not just for snapshot but it also works for any keyword (personally I use a similar search setting in vscode whenever I try to find docs as well).

grep -rni "snapshot" . --include="*.md" --exclude-dir=deps --exclude-dir=./doc/api --exclude-dir=./doc/changelogs --exclude-dir=out

This issue has been marked as stale due to 210 days of inactivity.
It will be automatically closed in 30 days if no further activity occurs. If this is still relevant, please leave a comment or update it to keep it open.

This issue has been automatically closed after 30 days of inactivity following its stale status (no activity for a total of 240 days).
If this is still relevant, feel free to reopen it or leave a comment with additional details so we can continue the discussion.

Navigation Menu

Repository navigation

Problems building with `--without-ssl` and openssl-related options in `NODE_OPTIONS` #59435

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	for (const std::string& error : result->errors()) {
	FPrintF(stderr, "%s: %s\n", result->args().at(0), error);
	}
	if (result->early_return()) {
	return result->exit_code_enum();
	}

	CHECK(!result->early_return());
	CHECK_EQ(result->exit_code(), 0);

Problems building with --without-ssl and openssl-related options in NODE_OPTIONS #59435

Description

Activity

joyeecheung commented on Aug 10, 2025

jasnell commented on Aug 10, 2025

jasnell commented on Aug 10, 2025

joyeecheung commented on Aug 11, 2025

joyeecheung commented on Aug 18, 2025

github-actions commented on Apr 19, 2026

github-actions commented on May 19, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Problems building with `--without-ssl` and openssl-related options in `NODE_OPTIONS` #59435