Skip to main content

​
Runtime errors

Error message
File must be a .ocat file. Use -f to force execution with other extensions
CauseYou ran ocat run on a file that does not have the .ocat extension, and the -f flag was not passed.FixRename the file to use the .ocat extension:
mv myfile.txt myfile.ocat
ocat run myfile.ocat
Or use the force flag to run the file without renaming it:
ocat run myfile.txt -f
Force mode bypasses the extension check but does not validate file contents. The file still needs to contain valid OCat code.
Error message
File <path> doesn't exist
CauseThe file path passed to ocat run does not exist on disk.FixVerify the path is correct and that you are running the command from the right directory:
# Check that the file exists
ls src/main.ocat

# Run from the correct directory
ocat run src/main.ocat
If you are inside a project managed by ocm, use ocm run instead — it reads the entry point from .ocat/config.json automatically.
Error messages
Undefined token

Unexpected token: <token>
CauseThe OCat parser encountered a token it did not recognise, or a token appeared in a position where it was not expected.FixCheck the line reported in the error. Common causes:
  • A typo in a keyword (prit instead of print)
  • Missing quotes around a string literal
  • An unsupported operator or symbol
// Incorrect
prit("Hello")

// Correct
print("Hello")
Error messages
Variable <name> is not declared

Function <name> is not declared
CauseYou are referencing a variable or function that has not been declared in the current scope.FixDeclare the variable before using it:
number x = 10
print(x)
For functions, ensure the func definition appears before the call:
func greet() {
    print("Hello")
}

call greet()
Error messages
Variable <name> is already declared

Function <name> is already declared
CauseA variable or function with that name was declared more than once in the same scope.FixRemove the duplicate declaration or rename one of them.
Error message
Variable <name> is const and can't be modified
CauseThe CantModifyConstError is defined in the source but the const enforcement logic is not yet active in the current runtime (1.3.x). The error class exists but is not triggered in practice. This will become relevant once const enforcement is enabled in a future release.Future fixOnce const enforcement is active, reassigning a const variable will raise this error. Declare the variable without const if you need to change its value.

​
Project and CLI issues

Causeocm run reads the project entry point from .ocat/config.json. If that file is missing, the command cannot determine which file to run.FixMake sure you are running ocm run from the root of your OCat project — the directory that contains the .ocat/ folder:
# Verify the config file is present
ls .ocat/config.json

# If it's missing, initialize the project first
ocm initialize
The .ocat/config.json file is created automatically by ocm initialize. If you created the project manually, ensure the file exists and contains a main field pointing to your entry file.
CauseThe module service resolves imports by trying the following paths in order:
  1. The exact path as written
  2. The path with .ocat appended
  3. The path with .oc appended
If none of those paths exist on disk, the module silently returns null and no symbols are imported.FixEnsure the imported file exists with one of the supported extensions:
// This import will resolve if any of these files exist:
// utils
// utils.ocat
// utils.oc
import "utils"

# Check that the file exists
ls utils.ocat
You do not need to include the extension in the import path — the runtime will find it automatically as long as the file uses .ocat or .oc.

​
Known historical bugs

Affected versions: 0.3.0Functions defined with func failed to execute correctly in version 0.3.0.Fix: Upgrade to 0.3.1 or later.
npm install -g oclang@latest
Affected versions: 1.3.0Variable declarations and print() statements were broken after the runner restructure introduced in 1.3.0.Fix: Upgrade to 1.3.1 or later.
npm install -g oclang@latest
Affected versions: 1.0.0The -f flag was always active in 1.0.0, meaning the extension check was never enforced regardless of whether you passed -f.Fix: Upgrade to 1.0.1 or later.
Affected versions: 1.0.0 – 1.1.0When an error was thrown, the CLI printed undefined instead of the actual error message.Fix: Upgrade to 1.1.1 or later.

​
Getting help

If your issue is not covered here, open an issue or browse existing reports on the GitHub repository:

GitHub Issues

Report bugs, request features, or search existing issues

Changelog

Check whether your issue was fixed in a newer release

Build docs developers (and LLMs) love

Get started for freeTalk to us