reference appendix errors debugging troubleshooting

Common Errors Reference

This is the page you'll visit when the compiler yells at you and the error message isn't quite self-explanatory. I've collected the most common ones here with explanations and fixes. If your error isn't listed, the relevant chapter in the language reference usually has the answer.

Compiler Errors

Type Errors

Cannot assign TYPE to variable of type TYPE

Error Message:

Cannot assign 'string' to variable of type 'int'

What happened: You tried to assign a value of one type to a variable of an incompatible type.

Fix: Make the types match, or use explicit conversion.

// Correct
int x = 42;
string s = "hello";

// With conversion
int y = 42;
string t = @convert<string>(y);  // "42"

Type mismatch in expression

Error Message:

Type mismatch: expected 'int' but got 'string'

What happened: You used incompatible types in an expression.

Fix: Make sure the operand types are compatible.

// Correct
int result = 5 + 3;
string text = "Count: " + 5;  // String concatenation is valid

Cannot call procedure in formula

Error Message:

Cannot call procedure 'updateState' in formula context

What happened: Formulas must be pure expressions -- they can't call procedures that might modify state. This is by design; formulas need to be safe to evaluate at any time.

Fix: Use a function instead of a procedure, or restructure so the formula doesn't need to call state-modifying code.

int counter = 0;

// Correct: use a function (not a procedure) for formulas
function calculate(int x) -> int {
  return x * 2;
}
public formula good = calculate(counter);

Cannot expose private data through public field

Error Message:

Cannot expose private field 'secret' through public field

What happened: You tried to make private data visible through a public field or formula. The compiler catches this at compile time so it can't leak in production.

Fix: Respect the privacy boundary. Use a policy if you want conditional visibility.

private principal owner;
private int secret = 42;
public int publicValue = 0;  // Separate public field

// Or use a policy
policy can_see { return @who == owner; }
use_policy<can_see> int conditionalValue;

Declaration Errors

Duplicate identifier

Error Message:

Duplicate identifier 'playerName' already defined

What happened: Two declarations use the same name in the same scope.

Fix: Use unique names.

// Correct: use unique names
int score;
string playerName;

Undefined identifier

Error Message:

Undefined identifier 'playerScore'

What happened: You referenced a variable or field that doesn't exist. Usually a typo.

Fix: Declare the identifier before using it, or check your spelling.

// Correct: declare the identifier before using it
int playerScore = 0;
public formula total = playerScore * 2;

Cannot reference forward-declared field in formula

Error Message:

Formula 'a' references 'b' which is declared after it

What happened: Formulas can only reference fields declared before them. This prevents circular dependencies.

Fix: Reorder your declarations so dependencies come first.

// Correct: dependencies come first
public int b = 5;
public formula a = b + 1;  // OK: b declared first

Channel and Message Errors

Message type required for channel

Error Message:

Channel 'process' requires a message type parameter

What happened: You declared a channel without specifying what message type it accepts.

Fix: Declare the message type and use it.

// Correct: declare the message type and use it
message ProcessData {
  int value;
}
channel process(ProcessData data) { }

Cannot use @who outside of channel/policy context

Error Message:

'@who' is not available in this context

What happened: You used @who somewhere there's no user context -- like document-level initialization outside of @construct.

Fix: Use @who only where a user identity exists.

// Correct
private principal owner;

@construct {
  owner = @who;  // OK: @who available in @construct
}

State Machine Errors

Invalid state label

Error Message:

Invalid state label '#invalidState' - state not defined

What happened: You tried to transition to a state that doesn't exist.

Fix: Define the state before transitioning to it.

// Correct: define all states before referencing them
@construct {
  transition #playing;
}

#playing {
  // State code
}

Cannot await outside of state machine

Error Message:

Cannot use 'await' outside of state machine context

What happened: You used await() on a future outside of a state block. Awaiting blocks execution, and only state machine blocks can block.

Fix: Move your async operations inside state blocks.

message Response {
  int value;
}

channel<Response> respond;
private principal player;

// Correct: async operations inside state blocks
#waiting {
  future<Response> f = respond.fetch(player);
  Response r = f.await();  // OK: inside state block
}

Table and Query Errors

Invalid table operation

Error Message:

Cannot insert into non-table type

What happened: You used the insert operator (<-) on something that isn't a table.

Fix: Make sure you're inserting into a table.

// Correct: use tables for insert operations
record Item { public int value; }
table<Item> items;

@construct {
  items <- {value: 5};  // OK: items is a table
}

Unknown field in where clause

Error Message:

Unknown field 'username' in query - did you mean 'name'?

What happened: You referenced a field that doesn't exist in the record type. The compiler sometimes even suggests what you might have meant (nice of it).

Fix: Check field names for typos.

record Player {
  public string name;
  public int score;
}

table<Player> players;

// Correct: use the actual field name
public formula found = iterate players where name == "Alice";

Web Handler Errors

Invalid web response field

Error Message:

Invalid field 'content' in web response - use 'html', 'json', etc.

What happened: You used an invalid field name in a web handler return statement.

Fix: Use one of the valid response fields: html, json, xml, css, js, asset, error, forward, redirect, etc.

// Correct: use valid response fields like html, json, etc.
@web get /page {
  return { html: "<h1>Hello</h1>" };  // OK: 'html' is valid
}

Path parameter type mismatch

Error Message:

Path parameter 'id' declared as 'string' but used as 'int' in path

What happened: Mismatch between the declared parameter type and how it's used.

Fix: Make the types consistent.

// Correct: path parameters use $name:type syntax
@web get /user/$id:int {
  return { json: { user_id: id } };
}

Runtime Errors

Connection Errors

Connection rejected

Error Message:

Connection rejected: @connected returned false

What happened: Your @connected handler returned false for this user.

Fix: Check your connection policy logic. If this is unexpected, trace through the logic to see why the user was rejected.

private principal owner;
bool allowPublicAccess = false;

@connected {
  // Ensure this returns true for valid users
  if (@who == owner) {
    return true;
  }
  if (allowPublicAccess) {
    return true;
  }
  return false;  // This causes the rejection
}

Channel Errors

Channel message rejected

Error Message:

Message to channel 'place_bet' was rejected

What happened: The channel handler returned early or the message was invalid.

Fix: Check guard conditions in your channel handler.

message Bet {
  int amount;
}

private principal currentPlayer;

channel place_bet(Bet bet) {
  // These guards can cause message rejection
  if (@who != currentPlayer) {
    return;  // Silent rejection
  }
  if (bet.amount <= 0) {
    return;  // Invalid bet
  }
  // Process valid bet
}

State Machine Errors

Document blocked waiting for input

Error Message:

Document is blocked waiting for input on channel 'response'

What happened: The state machine is waiting for a specific principal to send a message. This is usually expected behavior -- the document is asking for input and won't proceed until it gets it.

Fix: The specified user needs to respond, or you need to handle the timeout case.

message Response {
  int value;
}

channel<Response> response;
private principal player1;

#waiting {
  future<Response> f = response.fetch(player1);
  Response r = f.await();  // Blocks until player1 responds
}

Privacy Errors

Policy violation

Error Message:

Privacy policy 'can_view' returned false for viewer

What happened: A viewer tried to access data they're not authorized to see. This is usually working as intended -- the privacy system is doing its job.

Fix: If this is unexpected, review your policy logic.

private principal owner;
bool isPublic = false;

policy can_view {
  return @who == owner || isPublic;
}

Test Errors

Assertion failed

Error Message:

Assertion failed in test 'TestName' at line 42

What happened: An assert statement evaluated to false.

Fix: Debug the test. Figure out why your assumption about the state was wrong.

int counter = 0;

procedure increment() {
  counter++;
}

test MyTest {
  counter = 0;
  increment();
  assert counter == 1;  // Fails if increment() does not work correctly
}

Test blocked unexpectedly

Error Message:

Test 'AsyncTest' ended while document was blocked

What happened: The test completed but the document was still waiting for input. You forgot to @pump a message or @step to process it.

Fix: Make sure you provide all required messages and step through all pending state transitions.

message Input {
  int x;
}

channel<Input> input_ch;

#start {
  future<Input> f = input_ch.fetch(@no_one);
  Input in = f.await();
}

@construct {
  transition #start;
}

test AsyncTest {
  @step;           // Start state machine
  @pump {x: 5} into input_ch;  // Provide input
  @step;           // Process input
  assert !(@blocked);  // Verify not blocked
}

When You're Stuck

When you hit an error, here's my process:

  1. Read the error message -- Adama's errors are usually specific enough to point you in the right direction
  2. Check the line number -- the error tells you where the problem is
  3. Verify types -- most compiler errors are type mismatches
  4. Check declaration order -- formulas can only reference previously declared items
  5. Verify context -- some things only work in specific contexts (e.g., @who in channels, await in state blocks)
  6. Review privacy modifiers -- privacy errors often mean data is flowing somewhere it shouldn't
  7. Test incrementally -- add tests to verify each component works in isolation

If you hit an error not listed here, check the relevant chapter in the language reference, review the grammar appendix for correct syntax, or search existing examples.

Previous Operators
Next Cli