Open the editorEditor
Troubleshooting

What a Checkup finding means

Every finding Checkup can show, what it means, and how to fix it.

Open the editorAll the docs

Mokxi teamTroubleshooting

What you see

The Checkup is the Circuit Doctor inside Mokxi AI. It reads your wiring and your code together, in your browser, and stays quiet when it is not sure. Open it from Checkup in the serial monitor's bar or on the toolbar (see Checkup). Each finding is a card marked Problem, Check or Tip, with one sentence on what is wrong and a line on what to do. Where a fix is safe there is a button for it, and Ctrl+Z undoes it like any edit.

Each finding below has its short code in brackets. You never need it; it is there so you can match a finding to this page, or quote it when you write to us.

Power and ground

  • A supply is wired straight to ground (short_circuit). A wire, or a breadboard strip, joins 5V or 3V3 to GND. On a real board that heats the wires and can kill the USB port. Take out the wire (the Remove that wire button does it), or move the part so the two pins land in different strips. A second form says two different supplies share one wire: use one supply per rail.
  • Two grounds are not joined (ground_not_shared). A part takes its power from a battery or a supply, but its ground does not reach the board's GND, so the signal has no way back. Keep the supply and add one wire from its ground to the board's GND. The fix button draws it.
  • A module has no ground, or no power (module_no_gnd, module_no_vcc). Its GND or VCC pin is not connected, or goes somewhere that is not ground or a supply. Wire GND to the board's GND, and VCC to 5V or 3V3, whichever the part asks for.
  • A module's power is on VIN, and nothing feeds VIN (module_on_vin). VIN (RAW on some boards) is the input of the board's regulator. It has a voltage only when a battery or adapter is wired to it, not on USB. Move the module's VCC to 5V.
  • A part the sketch uses is not wired to anything (part_not_wired). The code talks to it, but none of its pins are connected. Wire its power, ground and signal pins to the board.
  • A module is powered from too low a voltage (module_low_supply). Power its VCC from 5V (VIN on an ESP32 DevKit). If its output then swings to 5 V and goes to a 3.3 V board, add a divider (1 kΩ and 2 kΩ).
  • 5 V on a 3.3 V pin (voltage_5v_on_3v3). A 5 V part's output, or a 5 V rail, reaches a pin that takes 3.6 V at most. The simulator carries on, a real board may not. Power the part from 3V3 if it works there (the Move it to 3V3 button does it where it can), or put a divider or a level shifter on that wire. A 3.3 V part on 5 V gets the same finding: power it from 3V3.
  • An output is wired straight to a rail (output_to_rail). A board pin set as an output goes straight to GND or to 5V, so it shorts when the code drives it the other way. Put the part, with its resistor, between the pin and the rail.
  • Two outputs on one wire (two_outputs). Two outputs fight when one says HIGH and the other LOW. Connect an output to inputs only.
  • A potentiometer can short the supply (pot_short). Its middle pin is on 5V or GND, so turned to the end it joins them. Wire the two outer pins to the supply and ground, and read the middle pin.

LEDs and other parts

  • An LED has no resistor (led_resistor). Real LEDs burn out without one. The fix button puts a 220 Ω resistor in series. LEDs strung leg to leg count as one string: one resistor anywhere in it is enough, and none is this finding, on the LED nearest the pin.
  • The resistor is too big (led_dim_resistor). So little current gets through that the LED is nearly dark. A project from Wokwi can carry this value and look fine there, because Wokwi lights an LED whatever its resistor. The fix button sets a value that lights it.
  • The resistor is too small (led_small_resistor). Too much current runs through the LED and the pin. Check the third color band: 22 Ω and 220 Ω differ only there. The fix button sets 220 Ω.
  • An LED is in backwards (led_reversed). Its anode (A, the longer leg) is on GND, and its cathode faces the pin, directly, through a resistor or through another LED. Turn it around. The fix button swaps its two wires.
  • Both legs of an LED on one net (led_shorted). Both legs are on GND, on one pin, or pushed into the same breadboard strip, so the LED can never light. Move one leg: A to its pin through a resistor, C to GND. A resistor between a leg and GND still counts: the fix button moves the resistor's other end to a free pin.
  • An LED's cathode on the supply (led_cathode_to_supply). Its short leg (C) is on 3V3 or 5V (often the + rail) and its long leg on a pin. A pin goes no higher than the supply, so it never lights. Move C to GND (the - rail). The fix button moves that wire to the board's GND. An LED with A on the supply and C on the pin, lit by a LOW, is right and not this.
  • A resistor that does nothing (resistor_dangling). One end is connected to nothing, or both ends are on the same net, so no current goes through it. A resistor for an LED goes in series: pin, resistor, the LED's anode. Where a pin is wired straight to the LED beside it, the fix button moves that wire to the resistor's free end. A resistor wired to nothing at all gets a tip: wire it in, or delete it.
  • A pin driving only a resistor to GND (pin_to_ground_resistor). The code drives the pin as an output, and its only part is a resistor straight to GND, so nothing lights. Put the LED after the resistor: pin, resistor, A, then C to GND. A pull-down resistor on an input pin is right and not this.
  • An electrolytic capacitor is in backwards (capacitor_reversed). Its striped leg is on the higher voltage. The simulator shows nothing, but a real one leaks, heats and can burst. The fix button turns it around.
  • A button that changes nothing (button_same_side). Both wires are on legs that are always joined inside the button. Move one wire to a leg on the other side, or turn the button a quarter turn. The fix button moves one wire for you.
  • A motor or servo on a GPIO pin (motor_on_gpio). A pin gives a few milliamps and a motor wants hundreds. Power a servo's VCC from 5V and keep only its signal on a pin (the fix button moves it to 5V). Drive a motor through a transistor or a motor driver such as the L298N.
  • One motor wired the other way around (motor_reversed). Two motors on one driver, with one motor's two wires crossed, so the same code turns them opposite ways and a car spins instead of going straight. Swap that motor's two wires, or its two IN pins in the code; the fix button swaps the wires. Motors drawn facing each other, like a car's two sides, are meant to be crossed, and the Checkup knows it: there, two motors wired alike get this finding, because the car spins on the spot.
  • I2C on the wrong pins (i2c_pins). SDA and SCL are swapped, or not on the pins the board uses for I2C. The finding names the right pins, and the fix button moves or swaps the wires.
  • A part burned out, or was pushed past its rating (part_damaged). The part is drawn dark, or ringed in amber when it was spared once. The finding says what it measured against the rating. Fix the cause, then press Stop and Run: every part starts whole again.

Pins and code

  • The code and the wire use different pins (pin_mismatch). The fix buttons change the number in the code, or move the wire.
  • A library uses a different pin from the wire (library_pin). For example a servo attached to one pin and wired to another. Make the two agree.
  • A pin the code uses has nothing on it (pin_unwired), or a wired part the code never uses (pin_unused). Wire the part to the pin the code uses, or change the code.
  • pinMode is missing (pinmode_missing). A pin written with digitalWrite stays an input, so an LED on it glows dimly or not at all. Add pinMode(pin, OUTPUT); in setup().
  • pinMode is set the wrong way (pinmode_wrong). The code writes to a pin set as an input, or reads a button on a pin set as an output.
  • analogRead on a pin with no analog input (analog_pin), or analogWrite on a pin with no PWM (pwm_pin). The finding lists the pins that can.
  • A button leaves its pin floating (button_floating). With nothing holding the pin, it reads random values. Use INPUT_PULLUP and wire the button to GND; the pin then reads LOW while pressed. A second form says the button goes to the supply while INPUT_PULLUP already holds the pin HIGH: wire it to GND instead.
  • A pin with no pull resistor inside (pin_no_pull). On an ESP32, GPIO 34 to 39 have none, so INPUT_PULLUP does nothing there. Add a 10 kΩ resistor, or move the button to a pin that has one.
  • A pin that works here but not on a real ESP32-S3 (s3_reserved_pin). On the ESP32-S3 boards with octal PSRAM (the N8R8 and N16R8 most people buy), GPIO 35, 36 and 37 belong to the PSRAM, and GPIO 19 and 20 are the USB port's D- and D+. Mokxi has no PSRAM, so a part or code on those pins works here, and on a real board it does not. Move it to a free pin such as 39 and change the pin in the code. See the ESP32-S3-DevKitC-1.
  • A part on pin 0 or 1 (serial_pin_used). On an Uno, Nano, Mega or Pro Mini those pins are RX and TX, wired to the chip that uploads sketches. It runs in Mokxi, but on a real board the part can stop the upload and garble Serial. Move it to a free pin and change the pin number in the code.
  • A serial module on pins 0 and 1 (serial_module_upload). A tip, not an error. On an Uno, Nano or Pro Mini a module's TX and RX on pins 0 and 1 share Serial with USB. It works, here and on the board, but on a real board unplug it from pin 0 while you upload, or move it to two other pins with SoftwareSerial.
  • A module's TX or RX on a pin that carries no data (serial_power_pin). A module's TX or RX pin (a Bluetooth, GPS or GSM module, say) is on IOREF, RESET, AREF, 5V, 3V3, VIN or GND, so it can never talk to the board. Wire its TX to the board's RX and its RX to the board's TX (pins 0 and 1 on an Uno), or to two other pins with SoftwareSerial.

Serial and timing

  • Serial.begin is missing (serial_begin). Nothing reaches the serial monitor until the port is started. The fix button adds Serial.begin(9600);.
  • The baud rates do not match, or one is unusual (serial_baud). The code talks at one speed and the serial monitor listens at another, so the output is garbage: the fix button puts the monitor's speed in the code. Or Serial.begin uses a speed that is not a standard one, so a real serial monitor would show garbage: the finding suggests the nearest standard speed.
  • A millis() time kept in an int (millis_overflow), or a time check that breaks when millis() rolls over. Keep times in an unsigned long, and compare millis() - start with the interval instead of adding. The fix button changes the type.
  • A long delay() can miss a button press (delay_button). A tip, not an error. Time things with millis() and debounce the button.

The circuit as a whole

  • The circuit cannot be read as it is drawn (circuit_unreadable). The detail says why. Undo the last change, or delete the wire or part it names.
  • A wire goes nowhere (wire_nowhere). One end points at a pin that is not there. The run leaves the wire out. Delete it, or draw it again.
  • A part this simulator does not know (part_unknown). If the page is older than the part, Reload brings it in and keeps your work. Otherwise the run leaves it out, so remove it if it should not be there.
  • Part of the circuit never settled (circuit_unsettled). Some wires kept flipping with nothing to slow them down, so the simulator held them and kept running. What those parts show may not match a real circuit. Check for two parts joined in a loop, or both legs of a part in one breadboard row.

Still stuck

Press Explain on a finding to ask Mokxi AI about it (it uses a question), or see nothing lights up for the checks the Checkup cannot make. If a finding looks wrong for your circuit, write to us from /support with its code and a link to the project.