Problems starting your program¶

You pressed Start Auton or Start Driver and did not get a running robot. Either nothing launched at all, or the program launched and failed during configure() or run(), before your autonomous() and driver() code ever got called.

The steps these problems come from are in Run your program.

Nothing happens, or a toast error appears¶

Starting a phase launches src/main.py from the open MARLIN project. If there is no MARLIN project open, the extension shows an error toast instead of starting anything.

Check that:

• a MARLIN project folder is open in VS Code. A single loose .py file is not a project. Use New Project, or open the project folder itself.
• your program is saved at src/main.py inside that project. Another filename or another location will not be picked up.

See Open a project and Your Program.

I pressed run and got "extension not reachable"¶

The play button furthest to the left in the editor title bar is VS Code's own Run Python File, not MARLIN's. It runs your file as a plain Python script, with no MARLIN link configured, so Robot() has nothing to talk to and you get the unreachable error from Setting up.

Use Start Auton or Start Driver, the two icons inside the green box in Start a phase, or the Match Control buttons. Both launch the program the way MARLIN needs.

The console says run() was not given a callback¶

Typical message:

[OUT] [API] the autonomous phase started, but run() was not given autonomous=;
the robot idles until the phase changes.

You pressed Auton, but run() was only given a driver function (or the other way round). This is not an error. MARLIN says so in the MARLIN Console and idles the robot until the phase changes.

The phase button chooses which of your functions runs. Auton runs autonomous(robot), and Driver runs driver(robot). Pass both if you want both:

robot.run(autonomous=autonomous, driver=driver)

Defining a function is not enough on its own. It has to be handed to run(). See Phase callbacks.

The robot will not enter a phase, and the battery is low¶

MARLIN blocks entry into an active phase when the robot brain's battery is below 8%. This is deliberate: a robot that browns out mid-phase is more dangerous than one that never starts. Once the warning has latched, the pack has to come back above 10% to clear it, so a battery hovering right at the limit does not flip between blocked and allowed.

Check the battery dial on the Robot Brain card. Charge or swap the battery, then start the phase again.

A red Python error appears before anything connects¶

If the console shows a traceback, such as SyntaxError, IndentationError, NameError, or ModuleNotFoundError for something other than marlin, the error is in your file. The program stopped before reaching MARLIN at all. Read the filename and line number in the traceback and fix that line.

Use the console's tags to tell whose message you are reading. [OUT] is the running program. An untagged [OUT] line is your own print() or traceback, while [OUT] [API] is a runtime message from the MARLIN library itself. [EXT] is the extension itself. See MARLIN Console.

My code changes did not take effect¶

Starting a phase restarts the program only if the file changed since it last started, and an edit you have not saved has not changed the file yet. Save with Ctrl+S (Cmd+S on macOS), then start the phase again.

If you are unsure whether the old program is still running, press Stop first. Stop always ends the program, even one stuck in a loop. See Your Program.

Configuration does not match¶

Robot.configure() compares the declared hardware with the response returned through the extension. A mismatch raises RuntimeError before anything moves.

Check every sensor, effector, and port entry against the physical robot configuration. Do not catch this error and continue into a match.

A port declaration is rejected¶

• Sensor port keys must be S1 through S6.
• Effector port keys must be M1 through M8.
• Sensor values must be a supported Sensor subclass: IMU or RadioBeacon.
• Effector values must be a supported Effector subclass: Thruster or Servo.
• configure() accepts at most 2 IMU sensors and at most 1 RadioBeacon sensor. Passing more raises ValueError.

Pass classes, not constructed objects:

sensors={"S1": IMU}
effectors={"M1": Thruster}

Robot.configure() times out¶

Typical message:

Timed out waiting for the robot to confirm its configuration.

configure() waits up to 2 seconds for the robot brain to echo the configuration. Check that:

• the Controller shows a live connection to the robot in the extension
• the robot is powered on
• the physical port wiring matches your configure() call.

Robot.run() hangs, then raises LinkError¶

run() waits up to 2 seconds for the extension to confirm it is ready. If no confirmation arrives, run() raises LinkError.

Check the extension status and the Controller-to-robot connection, then start the program again.