add nicer text to schema error validation

[kfirstri]

Note

Description

This PR improves schema validation error messages by including file paths in the error output. When schema validation fails, users will now see which specific file contains the invalid data, making it easier to locate and fix configuration issues. The SchemaValidationError class has been enhanced to accept an optional file path parameter, and all call sites have been updated to provide this context.

Related Issue

None

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

• Enhanced SchemaValidationError class to accept an optional filePath parameter
• Updated error messages to include file path when available (e.g., "Invalid entity file in /path/to/entity.jsonc")
• Updated hints to reference the specific file path for better user guidance
• Modified all 10 call sites across the codebase to pass file paths to SchemaValidationError
• Added comprehensive tests to verify error formatting with and without file paths
• Simplified error message construction in call sites by moving file path formatting into the error class

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (npm test)

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated AGENTS.md if I made architectural changes

Additional Notes

This change improves the developer experience when debugging schema validation errors by providing clear context about which file contains invalid data. The implementation is backward compatible - the file path parameter is optional, allowing the error to work without it if needed.

---

_{🤖 Generated by Claude | 2026-02-02 00:00 UTC}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.0.26-pr.177.b92d27f

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.0.26-pr.177.b92d27f"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.0.26-pr.177.b92d27f"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.0.26-pr.177.b92d27f
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}

[claude]

---

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

---

[claude]

Code Review

I found one issue that needs to be addressed:

Invalid Zod API usage in schema.ts

File: src/core/project/schema.ts:25-27

The code uses z.string({ error: "App name cannot be empty" }), but error is not a valid option for z.string() in Zod 4.x. This option will be silently ignored, and the custom error message won't work as intended.

Current code:

name: z.string({
  error: "App name cannot be empty"
}).min(1, "App name cannot be empty"),

Issue: The error property is not a valid Zod 4 option. The valid property is message, not error.

Suggested fix:

name: z.string().min(1, "App name cannot be empty"),

This is consistent with how error messages are handled elsewhere in the codebase (see

cli/src/core/project/schema.ts

Lines 38 to 40 in 6c95179

	export const AppConfigSchema = z.object({
	id: z.string().min(1, "id cannot be empty"),
	});

).

Since .min(1) already validates that the string is not empty, the redundant configuration object isn't needed.

[kfirstri]

Code Review

I found one issue that needs to be addressed:

Invalid Zod API usage in schema.ts

File: src/core/project/schema.ts:25-27

The code uses z.string({ error: "App name cannot be empty" }), but error is not a valid option for z.string() in Zod 4.x. This option will be silently ignored, and the custom error message won't work as intended.

Current code:

name: z.string({
  error: "App name cannot be empty"
}).min(1, "App name cannot be empty"),

Issue: The error property is not a valid Zod 4 option. The valid property is message, not error.

Suggested fix:

name: z.string().min(1, "App name cannot be empty"),

This is consistent with how error messages are handled elsewhere in the codebase (see

cli/src/core/project/schema.ts

Lines 38 to 40 in 6c95179

	export const AppConfigSchema = z.object({
	id: z.string().min(1, "id cannot be empty"),
	});

).
Since .min(1) already validates that the string is not empty, the redundant configuration object isn't needed.

here are the docs that show this is wrong https://zod.dev/error-customization?id=the-error-param