fix: hard fail on invalid railpack.json #226

iloveitaly · 2025-08-20T13:22:01Z

I noticed this while debugging my project's build failure. I kept getting a message about malformed railpack.json even though I did not provide one directly. It seems as through the generated railpack.json was incorrect but it did not cause the build to hard fail, it continued on without the generated railpack.json.

This change ensures that if invalid railpack.json is encountered, the CLI hard fails.

Breaking Change

Previously, if JSON did not conform to the schema it would just be ignored and the build would continue. With this change, the build will halt and force the user to fix or discard their schema. I prefer this more explicit approach.

examples/config-file/test.json

coffee-cup

What "generated railpack.json" file are you talking about? I kind of think that we should still be attempting to build if the users config file is malformed. Though could go either way

iloveitaly · 2025-08-20T20:11:22Z

What "generated railpack.json" file are you talking about?

This is hand-wavy on my end because I haven't read that part of the system.

What I was seeing in my project (railpack build) was:

no railpack* files
I got a warning that there was an error reading a railpack.json
I didn't really pay attention to it because (a) I didn't understand what the railpack.json was at the time (b) there wasn't a railpack.json file in my dir
What is seems like is happening is there is a railpack.json 'generated' by the build command, but it's invalid, and then it's passed to the actual LLB logic where it's ignored
This is the hand-wavy part since I decided to dig into the .dockerignore part of the system since I know that was causing issues.

I can report back when I dig into this more and understand exactly where this is failing.

iloveitaly · 2025-09-01T23:05:25Z

What "generated railpack.json" file are you talking about?

Ok, I discovered what was happening here:

In the build script I was testing, I had a railpack prepare call which dumped railpack.json. It seems like that command is resulting in invalid railpack.json. I was attempting to run railpack build directly, which I assumed would ignore railpack.json since I didn't specify it as a --config-file but it looks like it's read automatically.

Automatically consuming railpack.json without a warning feels wrong to me. I think we should only read this during build if specified explicitly. Wdyt?

I kind of think that we should still be attempting to build if the users config file is malformed

I disagree here:

If a railpack.json exists it was either written by the user or railpack prepare. If it's invalid, it's probably a user error.
Right now there's only a warning that the schema is invalid and unless you are watching it really quickly it quickly gets gobbled up by a bunch of plan info printing and docker build progress.
If a dev breaks railpack.json accidentally and a build continues, it could cause a container to get deployed with a build configuration that was not intended, which could result in the wrong start script running, site to break, etc.

Two other issues I found here:

If an abs path is specified in --config-file it always fails since the file path is assumed to relative to the application source. This bit me since the build script I was using was passing an abs path.
If the passed config file DNE it is ignored, similar to a railpack.json that can't be parsed

I've updated the PR to correct these. My general thinking here is the provider/detection logic should be "magical" but any user-specified configuration inputs should be strict to guarantee deterministic build plans.

coffee-cup

Automatically consuming railpack.json without a warning feels wrong to me. I think we should only read this during build if specified explicitly. Wdyt?

Can you expand on why it feels wrong? It is very standard across all tooling that supports a config file (Dockerfile, package.json, vite config, buildpacks).

Failing on an invalid railpack.json file makes sense then. Agree it will help avoid confusion. In your case I recommend naming the file railpack-plan.json

coffee-cup · 2025-09-02T20:22:28Z

core/core.go

+	// unless an absolute path, assume relative to the app source directory
+	var absConfigFileName string
+	if !filepath.IsAbs(configFileName) {
+		absConfigFileName = filepath.Join(app.Source, configFileName)


I think this is too dangerous to do since it means that you can read a config file outside of the app directory. It is especially a problem since the config file path can come from a user defined env var

RAILPACK_CONFIG_FILE=/something/you/dont/have/access/to

I can revert! I'll also update the docs/--help around this since it confused me.

Curious why that's a problem/security concern? If the user has access to those files during build, it doesn't seem risky to me.

iloveitaly · 2025-09-02T20:35:05Z

Can you expand on why it feels wrong? It is very standard across all tooling that supports a config file (Dockerfile, package.json, vite config, buildpacks).

On second thought, I'm wrong here. Most build tooling does automatically consume expected files, but most of the other CLI tools I use on a daily basis don't, which is why this felt wrong to me.

I think it's worth adding path to config file to use (default: railpack.json) to help output to make this more explicit.

coffee-cup · 2025-09-03T15:29:44Z

I think it's worth adding path to config file to use (default: railpack.json) to help output to make this more explicit.

That would make it much clearer!

helpful if we expect the build to fail. There shouldn't be too many of these, but we'll need at least a couple to make sure cases like railpack.json syntax errors hard fail.

…exist

I know basically nothing about Java and after I fixed the syntax error which was causing this config file to not be picked up, this started failing. The proper Zulu version check which is the main purpose of this is still working fine so I think it's fine to remove these custom commands.

iloveitaly · 2025-09-04T17:09:53Z

@coffee-cup this one is ready for final review.

iloveitaly force-pushed the railpack-json branch from 37b4f94 to 98bfe70 Compare August 20, 2025 14:31

iloveitaly commented Aug 20, 2025

View reviewed changes

examples/config-file/test.json Show resolved Hide resolved

iloveitaly requested a review from coffee-cup August 20, 2025 17:30

coffee-cup reviewed Aug 20, 2025

View reviewed changes

iloveitaly force-pushed the railpack-json branch 2 times, most recently from 5d86888 to 008efef Compare September 1, 2025 22:57

coffee-cup reviewed Sep 2, 2025

View reviewed changes

iloveitaly added 7 commits September 4, 2025 08:34

fix: hard fail if railpack.json cannot be parsed

5792860

test: add shouldFail test.json expression

42eeee3

helpful if we expect the build to fail. There shouldn't be too many of these, but we'll need at least a couple to make sure cases like railpack.json syntax errors hard fail.

test: bad json syntax failure

fe86a31

test: config file abs path, relative, and DNE cases

2d35aec

refactor: move hujson helper into internal helpers

55a306d

fix: support abs config file path, fail if config file path does not …

bf163ac

…exist

fix: document relative config file path, no abs config file support

352c3d3

iloveitaly force-pushed the railpack-json branch from fc43ea2 to 352c3d3 Compare September 4, 2025 15:14

iloveitaly added 6 commits September 4, 2025 09:29

fix: invalid config json

cf8334c

test: snapshot update

31c650e

test: remove abs file config test

b8e047c

fix: typo

7d4721f

test: snapshot update

40e9380

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: hard fail on invalid railpack.json #226

fix: hard fail on invalid railpack.json #226

Uh oh!

iloveitaly commented Aug 20, 2025 •

edited

Loading

Uh oh!

Uh oh!

coffee-cup left a comment

Uh oh!

iloveitaly commented Aug 20, 2025

Uh oh!

iloveitaly commented Sep 1, 2025

Uh oh!

coffee-cup left a comment

Uh oh!

coffee-cup Sep 2, 2025

Uh oh!

iloveitaly Sep 2, 2025

Uh oh!

iloveitaly commented Sep 2, 2025

Uh oh!

coffee-cup commented Sep 3, 2025

Uh oh!

iloveitaly commented Sep 4, 2025

Uh oh!

Uh oh!

fix: hard fail on invalid railpack.json #226

Are you sure you want to change the base?

fix: hard fail on invalid railpack.json #226

Uh oh!

Conversation

iloveitaly commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Breaking Change

Uh oh!

Uh oh!

coffee-cup left a comment

Choose a reason for hiding this comment

Uh oh!

iloveitaly commented Aug 20, 2025

Uh oh!

iloveitaly commented Sep 1, 2025

Uh oh!

coffee-cup left a comment

Choose a reason for hiding this comment

Uh oh!

coffee-cup Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

iloveitaly Sep 2, 2025

Choose a reason for hiding this comment

Uh oh!

iloveitaly commented Sep 2, 2025

Uh oh!

coffee-cup commented Sep 3, 2025

Uh oh!

iloveitaly commented Sep 4, 2025

Uh oh!

Uh oh!

iloveitaly commented Aug 20, 2025 •

edited

Loading