Troubleshooting and FAQ
The simulator
The LED does not light up
Look in the serial monitor for a [sim] line. The usual cause is a missing pinMode: the hint says digitalWrite on that pin does nothing yet. Add pinMode(pin, OUTPUT); in setup().
Also check that the pin in your code is the pin the LED is on. The pin map and the On the board list in the guide show which pin each part uses.
A button reads at random
The pin is floating: nothing holds it high or low while the button is up. Use pinMode(pin, INPUT_PULLUP);. With INPUT_PULLUP, the pin reads HIGH when the button is up and LOW while it is pressed.
analogWrite only switches the LED fully on or off
The pin has no PWM on that board. The [sim] hint lists the pins that have it. On the Uno and Nano, PWM is only on pins 3, 5, 6, 9, 10 and 11. In the designer, a part on such a pin shows the warning that it can blink but not fade.
My knob only goes up to 1023
That board's analog inputs are 10-bit: Arduino Uno, Nano and Mega, and NodeMCU read 0 to 1023. The ESP32 boards and the Pico read 0 to 4095. Use map() with the right top value.
The buzzer makes no sound
That is expected. The buzzer is shown, not played: the bench shows the note's frequency, such as ♪ 440 Hz, while it plays.
The run stops with a red error
The error under the editor starts with the line number and says what is wrong. Common ones:
is not declared: a misspelt name, or a variable used before it is declared.does not exist on the: the board has no pin with that number.has no analog input on the:analogRead()on a digital-only pin. The message lists the analog pins.is input only: an output on a pin that can only read, such as GPIO 34 to 39 on the ESP32 DevKit V1.is outside the array: an index past the end of an array.is not available in the simulator: a function the simulator does not have.
My sketch uses Wi-Fi, Bluetooth, a display or a library
The simulator does not run Wi-Fi, Bluetooth, I2C or SPI devices, displays or third-party libraries. Lines starting with #include are skipped, so the error comes when the sketch calls something from the library. Test the rest of the logic here, then deploy or export the sketch and run it on a real board.
'struct' is not supported in the simulator
Structs, classes, typedefs and pointers are not supported. Use separate variables or arrays instead.
It runs here but does not compile for the real board
The simulator is more forgiving than the real compiler, and the library projects have only been run in the simulator so far. Read the first error: line from the compiler, in the Deploy log or the Arduino IDE, and fix that line.
Why is there no Run button for the Raspberry Pi 4 / 5?
A Raspberry Pi 4 or 5 is a Linux computer that runs Python, and the app does not simulate it. Its projects show Runs on the Pi instead. Design the circuit, export the script and run it on the Pi. See Raspberry Pi 4 and 5.
Projects
Where are my projects saved?
On the device you made them on, only. On the website they are in the browser's storage for the site; in the apps, in the app's own data folder. Nothing is uploaded.
Clearing the website's data removes them, and a private browser window forgets them when it closes. To keep a project safe, or to move it to another device, export its Project file (.json) and import it where you need it. See Export and import.
I changed a lab's code and want the original back
Select Restore starter code, the round arrow at the top of the project, and confirm with Restore. The button is hidden on phone-sized screens, so use a wider window.
I cannot add or move parts in a library project
Library projects and labs have a fixed circuit. Select Customize to make your own copy, where you can change everything. See Design your own circuit.
A project is missing on my board
Some projects need more pins, more analog inputs or hardware the board does not have. The bottom of the project list names the projects not available on your board. RGB mood lamp needs the ESP32-S3's built-in RGB LED, and the NodeMCU, with one analog input, misses four more.
Import says the file is not a Circuit Lab project
Only project files exported from Circuit Lab can be imported: the .json from Project file (.json). A file for a board this version does not know cannot be imported either.
Deploy
Deploy says a web page cannot do this
Deploy does not work on the website or a hosted copy of it. Use the Linux or Windows app, or export the program and upload it with the Arduino IDE.
Has Deploy been tested on real boards?
Not yet. In version 1.0.0 it has been tested against a stand-in for arduino-cli. Please report what happens on your board on the issues page.
"Permission denied" on Linux
Your user may not open serial ports. Run this once, then log out and back in:
sudo usermod -aG dialout $USERNo board found
Use a USB cable that carries data: some only charge. Then select the refresh button in the dialog. On Windows, a board that does not show up usually needs the driver for its USB chip: CH340 for most clones, CP210x for many ESP boards.
The board did not enter upload mode
On ESP32 boards, hold BOOT (FLASH on a NodeMCU) while the upload starts. On the ESP32-S3, you can also hold BOOT, press and release RST, let go of BOOT and deploy again.
The Pico is not found
A Pico with nothing on it yet has no serial port. Unplug it, hold BOOTSEL while you plug it back in, pick No port: the board shows up as a USB drive and deploy.
Deploy from the snap does not work
Uploading from inside the snap has not been tried. It needs sudo snap connect circuit-lab:serial-port and sudo snap connect circuit-lab:raw-usb. If it still fails, use the .tar.gz build instead.
Can Circuit Lab show what the real board prints?
No. The serial monitor in Circuit Lab shows the simulation only. Use the Serial Monitor in the Arduino IDE at 115200 baud.
Install and platforms
Windows warns before running the app
The Windows build is not code-signed, so SmartScreen asks before the first run. Check that the zip came from the Circuit Lab release page. The Windows build has not been run on Windows yet; if it does not start, please report it.
The Linux app does not start
It needs GTK 3. Install your distribution's GTK 3 package and try again. Start it from a terminal to see any error message.
Is there an Android or iPhone app?
Not yet. Use the website in your phone's browser: it switches to a phone layout.
Does it need the internet?
The Linux and Windows apps work offline. The website needs a connection to load. Deploy needs one to download the add-on and each board's compiler the first time. The shop search buttons on the Parts tab open your browser.
Is it free? Does it collect anything?
Circuit Lab is free and open source under the MIT licence, with no account, no ads, no analytics and no tracking. Your projects and progress stay on your device.
Where do I report a problem?
On the Circuit Lab issues page on GitHub. Say which board, which project and which platform you were using.