Open the editorEditor
Troubleshooting

The sketch does not compile

Reading the Build tab, and the five things that usually cause it.

Open the editorAll the docs

Mokxi teamTroubleshooting

What you see: the Build tab

It is under the file strip in the code pane. It lists the steps with their timings, then the compiler's own output as clickable lines. Click a line and the editor jumps to that file, line and column.

The diagnostics are real clang diagnostics, unedited. A position in your sketch is a position in your sketch: the file is compiled under its own name, so the line numbers are yours and not some wrapper's.

A linker error has no position. ld.lld: error: undefined symbol: loop() appears as a line without a jump, because there is nothing to jump to.

1. A missing include

The most common one, and it has a symptom of its own: clang stops hard on a missing header. The build panel treats that as a failed build and shows the diagnostic rather than reporting a crash, so look for the file not found line.

Only the headers of your own project, its libraries and the runtime's own are there. The build itself has no network: a library is in the project before the build starts, or it is not there at all.

The runtime's own include the stock libraries tutorials use most, under their usual names: Servo.h, Wire.h, SPI.h, EEPROM.h, LiquidCrystal_I2C.h, Adafruit_GFX.h, Adafruit_SSD1306.h, Adafruit_NeoPixel.h, DHT.h, SoftwareSerial.h and TinyGPS++.h (the list, and what each covers). A header spelled in another case, as sketches written on Windows or a Mac often are (servo.h, liquidcrystal_i2c.h), is read as the one Mokxi has. For any other library the Build tab names the Mokxi header that does the same job, or offers Install with the library's name: one tap fetches it from the Arduino Library Manager, with the libraries it depends on, puts it in the project and builds again. The Arduino Library Manager search under the code finds any library in the official index by name, header or what it does. A library that does not list your board installs with a warning, and you can still try it. Your own files go in with Add library.

2. A function that is not in this runtime

The runtime is ours: freestanding C and C++ with the Arduino language reference's API. It carries pinMode, digitalWrite, digitalRead, analogWrite, analogRead, millis, micros, delay, delayMicroseconds, pulseIn, shiftIn, shiftOut, tone, noTone, attachInterrupt, Serial with parseInt and readStringUntil, String, floating point and the math library, the character tests, and sprintf with the rest of the C library tutorials use, plus shared drivers for the displays and the WS2812 strip (the list).

It is not avr-libc, not the Arduino core and not ESP-IDF, and none of those are fetched at build time. A call that resolves on a real Arduino may still not exist here (analogRead on a board whose converter is not modeled, say), and the build will say so.

3. The wrong file is main

A project has several files and one of them is where the compiler starts. If you renamed the sketch, check that the file you expect to be the entry point still is.

4. It compiled, but Run ran something else

Three things can happen when you press Run, and only one of them is a build:

  • the board runs a prebuilt example or an uploaded ELF, and nothing is compiled;
  • the board reuses the last build, because not one byte of the files changed;
  • the board is built.

An ELF you uploaded was not built from these files, so it wins: the board's program in the properties panel says Uploaded ELF while it is there. If the simulator refuses it, the message offers Use the code instead, which puts the board back on the code in the editor.

5. It compiles in the Arduino IDE, but not here

Two things the Arduino IDE does for a sketch, Mokxi does too, so a sketch copied from a tutorial does not trip on them.

  • Functions can be called before they are defined. The Arduino IDE writes a prototype for every function in the .ino tabs before it compiles them, and so does Mokxi, so loop() can call a function defined further down. Several .ino tabs are joined into one file, main tab first, as the IDE joins them. A function template gets its prototype with its template <typename T> line in front, as the IDE writes it. A few functions get no prototype: functions inside a class or namespace, a template with a default template argument, and a function whose parameter types are declared further down the sketch. For those, a call above the definition is use of undeclared identifier, and the Build tab says which line the function is on: move the function, or the type it uses, above the code that calls it, or put a one-line prototype such as void blinkTwice(); at the top.
  • Warnings do not stop the build. Your files are compiled with -Wall -Wextra, and the Build tab lists what they find, but the sketch still builds and runs, as it does in the IDE. An unused variable or parameter and a signed and unsigned comparison (int i < sizeof(pins)) can wait. if (x = HIGH) is worth fixing: a single = assigns, so the condition is always true, and you meant ==.

What is left is usually a library Mokxi does not carry, or a function that board's runtime leaves out: sections 1 and 2 above.

Build errors in plain words goes through the common messages one by one, and Arduino compile errors explained has them in both GCC's words and clang's.

If the first build hangs

It is not hanging, it is downloading. The toolchain is about seventy megabytes of clang and it streams once, then lives in the browser's cache. The steps in the Build tab say where it is. A return visit is about a second and a half, and an edit and run after that is a fraction of a second. If it fails to download, see the editor or the compiler will not load.

Still stuck

Compiling in the browser is the full contract: the command list, the cache keys and how the runtime is assembled. Or write to us from /support with the diagnostic.