# BlackLang Diagnostics This document is the stable reference for BlackLang diagnostic codes. Diagnostics are emitted by parser, validator, formatter, linter, generator, security, packaging, docs, and AI inspection commands. ## Contract Every diagnostic must keep this JSON shape: ```json { "file": "examples/warehouse/app.black", "line": 17, "column": 13, "code": "UNKNOWN_TABLE_COLUMN", "message": "Page Products table uses unknown field Product.barcode.", "suggestion": "Add the field to the source entity or remove it from columns." } ``` Rules: - `code` is the stable machine-readable key. - `message` explains what happened for humans. - `suggestion` tells the next repair step when possible. - `file`, `line`, and `column` should point at the source of the problem when available. - Do not reuse an old code for a different meaning. - If a code is renamed, document the migration in the same change. - AI agents should branch on `code`, not on `message` text. ## Agent Repair Order Use this order when multiple diagnostics exist: 1. Fix file, init, package, and build path errors. 2. Fix lexer and parser errors such as `UNCLOSED_*`, `UNEXPECTED_*`, and `INVALID_*_DECLARATION`. 3. Fix semantic missing/duplicate/unknown references. 4. Fix unsupported feature usage. 5. Fix source-security findings before packaging or deployment. ## Code Families ```text FILE_* filesystem read/write problems INIT_* project scaffold problems FORMAT_* deterministic formatting problems BUILD_* generator output problems PACKAGE_* production package problems HARDCODED_* likely source secret findings INVALID_* malformed syntax or malformed value MISSING_* required declaration or value is absent DUPLICATE_* same declaration appears more than once UNKNOWN_* reference points to a symbol that does not exist UNSUPPORTED_* value is known but not supported in this version UNCLOSED_* block or string was not closed UNEXPECTED_* token is valid text but invalid in that location AUTH_* auth prerequisite diagnostics INCOMPATIBLE_* semantic type mismatch diagnostics UNUSED_* declaration exists but is not used by its target ``` ## Current Codes ### File, Init, Format, Build, Package ```text BUILD_OUTPUT_ERROR BUILD_WRITE_ERROR FILE_READ_ERROR FILE_WRITE_ERROR FORMAT_REQUIRED INIT_DIRECTORY_ERROR INIT_FILE_EXISTS INIT_WRITE_ERROR MISSING_PACKAGE_MODE PACKAGE_CLEAN_ERROR PACKAGE_COPY_ERROR PACKAGE_CREATE_ERROR PACKAGE_OUTPUT_CONFLICT PACKAGE_PATH_ERROR ``` ### Parser Structure ```text INVALID_API_DECLARATION INVALID_APP_DECLARATION INVALID_AUTH_DECLARATION INVALID_AUTH_USER_DECLARATION INVALID_COMPONENT_DECLARATION INVALID_DATABASE_DECLARATION INVALID_ENTITY_DECLARATION INVALID_FORM_DECLARATION INVALID_LAYOUT_DECLARATION INVALID_PAGE_DECLARATION INVALID_ROLE_DECLARATION INVALID_SIDEBAR_DECLARATION INVALID_STATE_DECLARATION INVALID_TABLE_DECLARATION INVALID_TRANSITION_DECLARATION INVALID_WORKFLOW_DECLARATION UNCLOSED_API UNCLOSED_AUTH UNCLOSED_AUTH_USER UNCLOSED_COMPONENT UNCLOSED_DATABASE UNCLOSED_ENTITY UNCLOSED_FORM UNCLOSED_LAYOUT UNCLOSED_PAGE UNCLOSED_ROLE UNCLOSED_SIDEBAR UNCLOSED_STATE UNCLOSED_STRING UNCLOSED_TABLE UNCLOSED_TRANSITION UNCLOSED_WORKFLOW UNEXPECTED_API_TOKEN UNEXPECTED_AUTH_TOKEN UNEXPECTED_CHARACTER UNEXPECTED_COMPONENT_TOKEN UNEXPECTED_DATABASE_TOKEN UNEXPECTED_FORM_TOKEN UNEXPECTED_LAYOUT_TOKEN UNEXPECTED_PAGE_TOKEN UNEXPECTED_ROLE_TOKEN UNEXPECTED_SIDEBAR_TOKEN UNEXPECTED_TABLE_TOKEN UNEXPECTED_TOP_LEVEL UNEXPECTED_TRANSITION_TOKEN UNEXPECTED_WORKFLOW_TOKEN ``` ### App, Auth, Database ```text DUPLICATE_APP DUPLICATE_AUTH DUPLICATE_AUTH_USER_FIELD DUPLICATE_DATABASE INVALID_AUTH_SESSION INVALID_AUTH_STRATEGY INVALID_AUTH_USER_FIELD INVALID_DATABASE_URL INVALID_ENV_NAME MISSING_APP MISSING_AUTH_SESSION MISSING_AUTH_STRATEGY MISSING_AUTH_USER MISSING_DATABASE_URL UNSUPPORTED_AUTH_SESSION UNSUPPORTED_AUTH_STRATEGY UNSUPPORTED_AUTH_USER_FIELD_MODIFIER UNSUPPORTED_AUTH_USER_FIELD_TYPE ``` ### Entity, Field, Validation ```text DUPLICATE_ENTITY DUPLICATE_ENTITY_VALIDATION DUPLICATE_FIELD INCOMPATIBLE_VALIDATION_FIELDS INVALID_ENTITY_VALIDATION INVALID_FIELD INVALID_LENGTH_CONSTRAINT INVALID_NUMERIC_CONSTRAINT INVALID_REGEX_CONSTRAINT INVALID_VALIDATION_LITERAL MISSING_CONSTRAINT_VALUE MISSING_DEFAULT_VALUE MISSING_HELP_VALUE MISSING_LABEL_VALUE MISSING_MESSAGE_VALUE MISSING_PLACEHOLDER_VALUE MISSING_VALIDATION_CONDITION UNKNOWN_VALIDATION_FIELD UNSUPPORTED_FIELD_MODIFIER UNSUPPORTED_FIELD_TYPE UNSUPPORTED_LENGTH_CONSTRAINT UNSUPPORTED_NUMERIC_CONSTRAINT UNSUPPORTED_REGEX_CONSTRAINT UNSUPPORTED_URL_CONSTRAINT UNSUPPORTED_VALIDATION_OPERATOR ``` ### Page, Table, Form, Layout ```text DUPLICATE_LAYOUT DUPLICATE_PAGE DUPLICATE_SIDEBAR_ITEM DUPLICATE_UI_INTENT INVALID_ACTION_UI INVALID_PAGE_LAYOUT INVALID_SIDEBAR_ITEM INVALID_SOURCE INVALID_TABLE_PAGINATION INVALID_TABLE_SORT INVALID_UI_INTENT MISSING_PAGE_SOURCE UNKNOWN_ACTION_UI UNKNOWN_FILTER_FIELD UNKNOWN_FORM_FIELD UNKNOWN_PAGE_LAYOUT UNKNOWN_SEARCH_FIELD UNKNOWN_SIDEBAR_ITEM UNKNOWN_SORT_FIELD UNKNOWN_SOURCE_ENTITY UNKNOWN_TABLE_COLUMN UNSEARCHABLE_FIELD_TYPE UNSUPPORTED_ACTION UNSUPPORTED_PAGE_SIZE UNSUPPORTED_SORT_DIRECTION UNSUPPORTED_UI_MODE UNSUPPORTED_UI_TARGET_MODE ``` ### Role, Access, Permission ```text AUTH_REQUIRED_FOR_ACCESS DUPLICATE_ROLE INVALID_API_ACCESS INVALID_PERMISSION_DECLARATION MISSING_PERMISSION_RESOURCE UNKNOWN_ACCESS_ROLE UNKNOWN_PERMISSION_FIELD UNKNOWN_PERMISSION_RESOURCE UNSUPPORTED_API_ACCESS UNSUPPORTED_PERMISSION_ACTION UNSUPPORTED_PERMISSION_EFFECT ``` ### API Contract ```text DUPLICATE_API DUPLICATE_API_PARAM DUPLICATE_API_QUERY DUPLICATE_API_ROUTE INVALID_API_METHOD INVALID_API_PARAM INVALID_API_PATH INVALID_API_QUERY INVALID_API_WEBHOOK MISSING_API_METHOD MISSING_API_PATH MISSING_API_PATH_PARAM UNSUPPORTED_API_METHOD UNSUPPORTED_API_PARAM_TYPE UNSUPPORTED_API_QUERY_TYPE UNUSED_API_PARAM ``` ### Workflow ```text AUTH_REQUIRED_FOR_WORKFLOW_ALLOW DUPLICATE_WORKFLOW DUPLICATE_WORKFLOW_STATE DUPLICATE_WORKFLOW_TRANSITION INVALID_TRANSITION_FROM INVALID_TRANSITION_TO INVALID_WORKFLOW_SOURCE MISSING_TRANSITION_FROM MISSING_TRANSITION_TO MISSING_WORKFLOW_SOURCE MISSING_WORKFLOW_STATES MISSING_WORKFLOW_STATUS_FIELD UNKNOWN_TRANSITION_FROM UNKNOWN_TRANSITION_TO UNKNOWN_WORKFLOW_ALLOW_ROLE UNKNOWN_WORKFLOW_SOURCE UNSUPPORTED_WORKFLOW_STATUS_FIELD_TYPE ``` ### State And Component ```text DUPLICATE_COMPONENT DUPLICATE_COMPONENT_INPUT DUPLICATE_COMPONENT_VARIANT DUPLICATE_STATE DUPLICATE_STATE_FIELD DUPLICATE_STATE_MODAL INVALID_COMPONENT_INPUT INVALID_COMPONENT_VARIANT INVALID_STATE_FIELD INVALID_STATE_MODAL MISSING_COMPONENT_VARIANT_CONDITION UNSUPPORTED_COMPONENT_INPUT_TYPE UNSUPPORTED_STATE_FIELD_TYPE UNSUPPORTED_STATE_MODAL_DEFAULT ``` ### AI Tooling And Docs ```text MISSING_AFFECTED_SYMBOL UNKNOWN_AGENT_COMMAND UNKNOWN_AFFECTED_SYMBOL UNKNOWN_DOC_KEYWORD UNKNOWN_EXPLAIN_KEYWORD UNKNOWN_SECURITY_COMMAND UNKNOWN_THEME_COMMAND ``` ### Theme And UI Profile ```text DUPLICATE_THEME_TOKEN DUPLICATE_UI_BASELINE DUPLICATE_UI_MODE DUPLICATE_UI_SLOT INVALID_UI_BASELINE INVALID_THEME_DECLARATION INVALID_THEME_LOCKED INVALID_THEME_TARGET INVALID_THEME_TOKEN INVALID_THEME_VERSION INVALID_UI_MODE INVALID_UI_PROFILE LOCKED_UI_MODE_REMOVED MISSING_STANDARD_UI_MODE MISSING_UI_LOCK_BASELINE MISSING_THEME_DECLARATION MISSING_THEME_VERSION MISSING_UI_MODES MISSING_UI_PROFILE MISSING_UI_PROFILE_VERSION NON_APPEND_ONLY_UI_SLOT ``` ### Source Security ```text HARDCODED_DATABASE_URL HARDCODED_PRIVATE_KEY HARDCODED_TOKEN ``` ## Common Fix Patterns ```text UNKNOWN_* add the referenced symbol or remove the reference DUPLICATE_* keep one declaration and delete or rename the duplicate MISSING_* add the required block, field, value, or option INVALID_* rewrite the syntax to match the documented shape UNSUPPORTED_* use a supported v0.1 value or wait for a later language phase UNCLOSED_* add the missing closing quote or brace UNEXPECTED_* move the token to a valid block or remove it HARDCODED_* move secret values to env or a secret manager ```