-10

website/content/docs/cli/07-fetch.md

reviewed

··· 295 295 ### Permission Errors 296 296 297 297 Ensure you have write permissions for the project directory to create `.mlf/`. 298 298 - 299 299 - ## Future Features 300 300 - 301 301 - Planned enhancements: 302 302 - 303 303 - - `--force` flag to re-fetch cached lexicons 304 304 - - Version pinning (fetch specific lexicon versions) 305 305 - - Private/authenticated repositories 306 306 - - Offline mode with local cache 307 307 - - Fetch from local directories

-335

website/content/docs/cli/08-errors.md

reviewed

··· 1 1 - +++ 2 2 - title = "Error Messages" 3 3 - description = "Understanding MLF error diagnostics" 4 4 - weight = 8 5 5 - +++ 6 6 - 7 7 - MLF provides rich, helpful error messages with source code context and suggestions for fixing issues. 8 8 - 9 9 - ## Error Format 10 10 - 11 11 - All MLF errors follow this format: 12 12 - 13 13 - ``` 14 14 - × Error title 15 15 - ╭─[file.mlf:5:12] 16 16 - 5 │ author: ProfileView, 17 17 - · ^^^^^^^^^^^ error message 18 18 - ╰──── 19 19 - help: Suggestion for fixing the issue 20 20 - ``` 21 21 - 22 22 - **Components:** 23 23 - - **× Error title** - Brief description of the error 24 24 - - **Source location** - File name, line, and column 25 25 - - **Source context** - The relevant code snippet 26 26 - - **Error span** - Highlighted location with `^^^` 27 27 - - **help:** - Actionable suggestion for fixing 28 28 - 29 29 - ## Common Errors 30 30 - 31 31 - ### Parse Errors 32 32 - 33 33 - #### Expected Token 34 34 - 35 35 - ``` 36 36 - × Expected '}', found ',' 37 37 - ╭─[thread.mlf:10:5] 38 38 - 10 │ title: string, 39 39 - · ^ expected '}' 40 40 - ╰──── 41 41 - help: Check for missing closing braces or extra commas 42 42 - ``` 43 43 - 44 44 - **Cause:** Syntax error in MLF code 45 45 - 46 46 - **Fix:** Correct the syntax according to MLF grammar 47 47 - 48 48 - #### Invalid Identifier 49 49 - 50 50 - ``` 51 51 - × Invalid identifier: '123invalid' 52 52 - ╭─[thread.mlf:5:5] 53 53 - 5 │ 123invalid: string, 54 54 - · ^^^^^^^^^^ identifiers cannot start with numbers 55 55 - ╰──── 56 56 - help: Identifiers must start with a letter or underscore 57 57 - ``` 58 58 - 59 59 - **Cause:** Identifier doesn't follow naming rules 60 60 - 61 61 - **Fix:** Start identifiers with letters or underscores 62 62 - 63 63 - ### Type Errors 64 64 - 65 65 - #### Undefined Reference 66 66 - 67 67 - ``` 68 68 - × Undefined reference to 'ProfileView' 69 69 - ╭─[thread.mlf:8:12] 70 70 - 8 │ author: ProfileView, 71 71 - · ^^^^^^^^^^^ 'ProfileView' is not defined 72 72 - ╰──── 73 73 - help: Make sure this type is defined in the same file or imported via 'use'. 74 74 - ``` 75 75 - 76 76 - **Causes:** 77 77 - - Type is not defined 78 78 - - Type is in another file and not imported 79 79 - - Typo in type name 80 80 - 81 81 - **Fixes:** 82 82 - - Define the type in the same file 83 83 - - Use `mlf fetch` to download external lexicons 84 84 - - Add a `use` statement (if MLF supports imports) 85 85 - - Check spelling 86 86 - 87 87 - #### Type Mismatch 88 88 - 89 89 - ``` 90 90 - × Type mismatch: expected integer, found string 91 91 - ╭─[thread.mlf:12:15] 92 92 - 12 │ count: string, 93 93 - · ^^^^^^ expected integer type 94 94 - ╰──── 95 95 - help: Change this to 'integer' or update the constraint 96 96 - ``` 97 97 - 98 98 - **Cause:** Field type doesn't match its definition 99 99 - 100 100 - **Fix:** Update the type to match the schema 101 101 - 102 102 - ### Constraint Errors 103 103 - 104 104 - #### Invalid Constraint 105 105 - 106 106 - ``` 107 107 - × Invalid constraint for type 'integer': 'maxLength' 108 108 - ╭─[thread.mlf:15:9] 109 109 - 15 │ maxLength: 100, 110 110 - · ^^^^^^^^^ 'maxLength' is only valid for string types 111 111 - ╰──── 112 112 - help: Use 'maximum' for integer constraints 113 113 - ``` 114 114 - 115 115 - **Cause:** Constraint doesn't apply to the type 116 116 - 117 117 - **Fix:** Use the correct constraint for the type: 118 118 - - String: `maxLength`, `minLength`, `maxGraphemes`, `minGraphemes` 119 119 - - Integer: `minimum`, `maximum` 120 120 - - Array: `maxLength`, `minLength` 121 121 - 122 122 - #### Constraint Value Error 123 123 - 124 124 - ``` 125 125 - × Constraint value must be positive 126 126 - ╭─[thread.mlf:18:20] 127 127 - 18 │ maxLength: -10, 128 128 - · ^^^ negative value not allowed 129 129 - ╰──── 130 130 - help: Use a positive integer value 131 131 - ``` 132 132 - 133 133 - **Cause:** Constraint value is invalid 134 134 - 135 135 - **Fix:** Use a valid value according to the constraint rules 136 136 - 137 137 - ### Record Errors 138 138 - 139 139 - #### Missing Record Key 140 140 - 141 141 - ``` 142 142 - × Record definition must specify a key type 143 143 - ╭─[thread.mlf:3:1] 144 144 - 3 │ record main { 145 145 - · ^^^^^^^^^^^ missing key specification 146 146 - ╰──── 147 147 - help: Add 'key: "tid"' or another valid key type to the record 148 148 - ``` 149 149 - 150 150 - **Cause:** Record doesn't specify how records are keyed 151 151 - 152 152 - **Fix:** Add a key specification to the record definition 153 153 - 154 154 - ### XRPC Errors 155 155 - 156 156 - #### Invalid Response Code 157 157 - 158 158 - ``` 159 159 - × Invalid HTTP response code: 999 160 160 - ╭─[api.mlf:25:5] 161 161 - 25 │ 999: error, 162 162 - · ^^^ response code must be between 200-599 163 163 - ╰──── 164 164 - help: Use a valid HTTP status code 165 165 - ``` 166 166 - 167 167 - **Cause:** Invalid HTTP status code in query/procedure 168 168 - 169 169 - **Fix:** Use standard HTTP status codes (200, 400, 401, 404, 500, etc.) 170 170 - 171 171 - #### Missing Required Response 172 172 - 173 173 - ``` 174 174 - × Query/procedure must define at least one success response 175 175 - ╭─[api.mlf:20:1] 176 176 - 20 │ query getProfile(...) { 177 177 - · ^^^^^^^^^^^^^^^^^^^^^ no 200-level responses defined 178 178 - ╰──── 179 179 - help: Add at least one 2xx response (typically 200) 180 180 - ``` 181 181 - 182 182 - **Cause:** XRPC method has no success responses 183 183 - 184 184 - **Fix:** Add a 200-level response 185 185 - 186 186 - ### Union Errors 187 187 - 188 188 - #### Empty Union 189 189 - 190 190 - ``` 191 191 - × Union must have at least one type 192 192 - ╭─[thread.mlf:30:15] 193 193 - 30 │ data: unit | , 194 194 - · ^ empty union 195 195 - ╰──── 196 196 - help: Add at least one type to the union 197 197 - ``` 198 198 - 199 199 - **Cause:** Union has no types 200 200 - 201 201 - **Fix:** Add types to the union: `string | integer` 202 202 - 203 203 - #### Duplicate Union Types 204 204 - 205 205 - ``` 206 206 - × Duplicate type in union: 'string' 207 207 - ╭─[thread.mlf:32:20] 208 208 - 32 │ data: string | string, 209 209 - · ^^^^^^ duplicate type 210 210 - ╰──── 211 211 - help: Remove duplicate types from the union 212 212 - ``` 213 213 - 214 214 - **Cause:** Same type appears multiple times in union 215 215 - 216 216 - **Fix:** Remove duplicates 217 217 - 218 218 - ## Validation Errors 219 219 - 220 220 - ### Record Validation 221 221 - 222 222 - ``` 223 223 - ✗ Record validation failed with 2 error(s): 224 224 - • Field 'title' is required but missing 225 225 - • Field 'count': expected integer, found "123" 226 226 - ``` 227 227 - 228 228 - **Cause:** JSON record doesn't match lexicon schema 229 229 - 230 230 - **Fix:** Update the JSON to match the schema 231 231 - 232 232 - ## Generation Errors 233 233 - 234 234 - ### File Read Error 235 235 - 236 236 - ``` 237 237 - Failed to read file: permission denied 238 238 - ``` 239 239 - 240 240 - **Cause:** Cannot read input file 241 241 - 242 242 - **Fix:** Check file permissions and path 243 243 - 244 244 - ### Type Resolution Error 245 245 - 246 246 - ``` 247 247 - Type resolution error: circular reference detected 248 248 - ``` 249 249 - 250 250 - **Cause:** Types reference each other in a cycle 251 251 - 252 252 - **Fix:** Break the circular dependency 253 253 - 254 254 - ### Code Generation Error 255 255 - 256 256 - ``` 257 257 - Generator 'typescript' not found 258 258 - ``` 259 259 - 260 260 - **Cause:** Generator feature not enabled 261 261 - 262 262 - **Fix:** Install with `--features typescript` or use `--all-features` 263 263 - 264 264 - ## Fetch Errors 265 265 - 266 266 - ### DNS Error 267 267 - 268 268 - ``` 269 269 - ✗ DNS lookup failed: No TXT record found for _lexicon.place.stream 270 270 - ``` 271 271 - 272 272 - **Cause:** Domain has no lexicon TXT record 273 273 - 274 274 - **Fix:** Verify the namespace is correct and has published lexicons 275 275 - 276 276 - ### Network Error 277 277 - 278 278 - ``` 279 279 - ✗ Failed to fetch lexicon records: connection timeout 280 280 - ``` 281 281 - 282 282 - **Cause:** Network connectivity issues 283 283 - 284 284 - **Fix:** Check internet connection and try again 285 285 - 286 286 - ### Parse Error 287 287 - 288 288 - ``` 289 289 - ✗ Failed to parse lexicon JSON: unexpected end of input 290 290 - ``` 291 291 - 292 292 - **Cause:** Malformed JSON from remote repository 293 293 - 294 294 - **Fix:** Report issue to namespace maintainer 295 295 - 296 296 - ## Exit Codes 297 297 - 298 298 - All MLF commands use standard exit codes: 299 299 - 300 300 - - `0` - Success 301 301 - - `1` - Error occurred 302 302 - 303 303 - Use in scripts: 304 304 - 305 305 - ```bash 306 306 - if mlf check; then 307 307 - echo "✓ Valid" 308 308 - else 309 309 - echo "✗ Invalid" 310 310 - exit 1 311 311 - fi 312 312 - ``` 313 313 - 314 314 - ## Tips for Reading Errors 315 315 - 316 316 - 1. **Read the title** - Gives you the high-level issue 317 317 - 2. **Check the location** - Find the exact line and column 318 318 - 3. **Examine the span** - See what code is problematic 319 319 - 4. **Follow the help** - Actionable suggestions for fixes 320 320 - 5. **Look for patterns** - Similar errors often have similar fixes 321 321 - 322 322 - ## Reporting Bugs 323 323 - 324 324 - If you encounter an error that seems like a bug: 325 325 - 326 326 - 1. Note the exact error message 327 327 - 2. Create a minimal reproduction case 328 328 - 3. Check if it's a known issue 329 329 - 4. Report at: https://github.com/anthropics/claude-code/issues 330 330 - 331 331 - Include: 332 332 - - MLF version (`mlf --version`) 333 333 - - Complete error message 334 334 - - Minimal MLF code that reproduces the issue 335 335 - - Expected behavior vs actual behavior