Troubleshooting (WIP)
A quick reference for common errors when deploying definitions and calling Custom API endpoints.
Definition Won't Deploy
Symptom: POST to /minimal/rest/definition/v1 returns an error.
| Cause | Fix |
|---|---|
| Missing required header | Ensure all five Auto API headers plus Content-Type: application/x-yaml are present |
X-User-Roles not power or admin | Deploying a definition requires power or admin role |
| Malformed YAML | YAML is whitespace-sensitive — use spaces, never tabs. Validate with yamllint.com |
Invalid ULID in identifiers | All IDs must be valid ULIDs — 26 uppercase alphanumeric characters |
feature_id conflict | Each definition must have a unique feature_id — generate a new ULID for every new definition |
Wrong Content-Type | Must be application/x-yaml — not application/json or text/plain |
Endpoint Returns 403
Symptom: Definition deployed successfully but calling the endpoint returns 403 Forbidden.
| Cause | Fix |
|---|---|
Role in X-User-Roles not in permission[] | Add the user's role to permission in the definition, or pass a role that is already permitted |
Wrong X-Org-Id or X-Project-Id | These must match the org_id and project_id in the definition's identifiers |
Missing X-User-Roles header | All five Auto API headers are required on every call |
SQL Step Fails
Symptom: Request fails mid-execution, no data returned.
| Cause | Fix |
|---|---|
| Wrong table or column name | Check the exact table and column names in your database — they are case-sensitive |
?:field not found in previous step | The field name in ?:field must exist in the result of the preceding step |
| String param missing quotes | String bindings require single quotes — use '?:name' not ?:name |
| Numeric param has quotes | Numeric bindings must not have quotes — use ?:id not '?:id' |
| Database connection fails | Verify source_ip, port, username, password, and name in the database section |
| Query timeout | Increase timeout_secs in the database section for slow queries |
Lark Step Fails
Symptom: Starlark step errors or returns unexpected output.
| Cause | Fix |
|---|---|
result not assigned | Every Lark step must assign a value to result — this becomes the step output |
Accessing step_N that doesn't exist | Steps are zero-indexed — step_0 is the first step. Check your step count |
| Using Python syntax not supported in Starlark | Starlark does not support f-strings, import, class, generators, or try/except — use supported syntax only |
| Module not loaded | Built-in modules must be loaded explicitly — load("math", "upby10") before use |
| Iterating non-list | If a SQL step returns one row, it may be a dict not a list — check the shape of step_N before iterating |
Wrong or Empty Response
Symptom: Request succeeds (200 OK) but response is empty or not what you expect.
| Cause | Fix |
|---|---|
All steps have omit: true | At least one step must have omit: false (or omit not set) to return data |
| Stale cached response | If cache_result: true, Minimal may return a cached response — disable caching during development |
| Wrong step returning data | Check which steps have omit: false — only those appear in the response |
?version= pointing to wrong version | Confirm the version in the query param matches the deployed definition version |
Version Issues
Symptom: Wrong version of the endpoint is being called, or rollback triggered unexpectedly.
| Cause | Fix |
|---|---|
?version= missing | Always pass ?version= — e.g. ?version=0.1 |
?version= value doesn't match any deployed version | Check the http.version in your deployed YAML — must match exactly |
| Rollback triggered on deploy | The new version has an error Minimal caught — fix the definition and redeploy with an incremented version |
| Old response returned after update | If cache_result: true, the cache may still hold the old response — disable and re-enable after confirming the update works |
YAML Formatting Issues
YAML is the most common source of deploy failures. Rules to follow:
- Use spaces, never tabs — tabs break YAML parsing silently
- Indent consistently — 2 spaces per level throughout
- Quote strings with special characters — passwords, values with
:or#must be quoted - Multiline SQL uses
|— the pipe character preserves line breaks
# ✅ Correct
- sql: |
SELECT * FROM users
omit: true
# ❌ Wrong — tab indentation
- sql: |
SELECT * FROM users
omit: true
Validate your YAML before deploying at yamllint.com.
Still Stuck?
Check the Minimal server logs for the full error message — runtime errors from SQL and Lark steps are logged with the step number and definition feature_id.