> For the complete documentation index, see [llms.txt](https://docs.protoboard.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.protoboard.xyz/user-guide/fixing-errors.md).

# Fixing Errors

Identify, locate, and fix common validation errors to get your board from red to green.

## Goal

Learn the most common validation errors you will encounter in Protoboard and how to resolve each one efficiently.

***

## The fix workflow

Every error follows the same basic resolution process:

{% stepper %}
{% step %}

#### Identify the issue

Open the **Board Review** panel (shield icon in the left sidebar). Review the DRC issues grouped by severity. Each card tells you which harness is affected, which parts are involved, and the reasons for the issue.
{% endstep %}

{% step %}

#### Locate it on the canvas

Click the **"Locate on board"** button (crosshair icon) on the issue card. The canvas pans and zooms to the affected element so you can see it in context.
{% endstep %}

{% step %}

#### Fix it

Select the affected harness or part and make corrections in the **Inspector** panel. For complex issues, use **ProtoBot** to get AI-assisted fix suggestions.
{% endstep %}

{% step %}

#### Re-validate

Return to the Board Review panel to confirm the issue is resolved. The harness color on the canvas should update (green = fully configured, amber = still needs work).
{% endstep %}
{% endstepper %}

{% hint style="success" %}
**Fix blockers first.** BLOCKED issues prevent your board from being valid. PARTIAL issues can sometimes be acceptable for early-stage prototyping, but should be resolved before finalizing your design.
{% endhint %}

***

## Common error patterns and fixes

### 1. Missing resource allocation

{% columns %}
{% column %}
**Symptom**: Interface links exist and function links are set up, but the harness is amber instead of green.

**Cause**: The underlying part resources (physical pins, peripherals) have not been mapped to the interface functions.
{% endcolumn %}

{% column %}
**Fix**:

1. Select the harness in the Inspector
2. Look for the resource allocation section
3. Click **Auto-allocate** to let Protoboard assign resources, or manually pick the specific pins/peripherals you want
   {% endcolumn %}
   {% endcolumns %}

***

### 2. Voltage mismatch

{% columns %}
{% column %}
**Symptom**: DRC reports a voltage incompatibility between two connected parts. For example, a 3.3V sensor connected directly to a 5V microcontroller GPIO.

**Cause**: The electrical specifications of the connected interfaces operate at different voltage levels.
{% endcolumn %}

{% column %}
**Fix**:

* Add a **level shifter** between the two parts to translate voltage levels
* Or add a **voltage regulator** if the mismatch is on a power connection
* Or swap one of the parts for a version that operates at the matching voltage
  {% endcolumn %}
  {% endcolumns %}

***

### 3. Bus or address conflicts

{% columns %}
{% column %}
**Symptom**: DRC reports an address conflict on a shared bus (e.g., two I2C devices with the same address).

**Cause**: Multiple devices on the same bus are configured with identical addresses.
{% endcolumn %}

{% column %}
**Fix**:

* **Change the address** on one of the devices (many I2C devices have configurable address pins)
* Add an **I2C multiplexer** to isolate devices on separate bus segments
* Move one device to a different bus instance
  {% endcolumn %}
  {% endcolumns %}

***

### 4. Protocol role mismatch

{% columns %}
{% column %}
**Symptom**: DRC reports "incompatible" when you try to link two interfaces of the same protocol type. For example, two I2C Masters.

**Cause**: Both interfaces have the same role instead of complementary roles.
{% endcolumn %}

{% column %}
**Fix**:

1. Select one of the parts
2. Open the Inspector and navigate to the interface definition
3. Change the role to the complementary value (e.g., change one Master to Slave)

Refer to the [compatibility rules](/user-guide/connections-and-compatibility.md#compatibility-rules) for the full list of complementary role pairs.
{% endcolumn %}
{% endcolumns %}

***

### 5. Capacity exceeded

{% columns %}
{% column %}
**Symptom**: DRC reports that a part cannot accept more connections of a given type. For example, you have connected four I2C devices to a microcontroller that only supports two I2C bus instances.

**Cause**: The part has reached its maximum number of instances for that interface type.
{% endcolumn %}

{% column %}
**Fix**:

* **Reduce connections** by consolidating or removing unnecessary links
* Add a **hub or expander** to increase the available capacity
* Choose a different part with more interface instances (e.g., a microcontroller with more I2C peripherals)
  {% endcolumn %}
  {% endcolumns %}

***

## Quick-reference fix table

| Error                              | Root cause                       | Quick fix                              |
| ---------------------------------- | -------------------------------- | -------------------------------------- |
| Amber harness, no DRC errors shown | Missing resource allocation      | Auto-allocate in Inspector             |
| Voltage mismatch                   | Different voltage domains        | Add level shifter or regulator         |
| Address conflict                   | Duplicate bus address            | Change address or add multiplexer      |
| Incompatible link                  | Same role on both sides          | Change one role to its complement      |
| Capacity exceeded                  | Too many interface instances     | Add hub/expander or swap part          |
| Red harness, no links              | Harness drawn but not configured | Add interface links and function links |

***

## Common failures

<details>

<summary>I fixed the issue but the Board Review still shows it</summary>

Board Review updates after changes are applied. Make sure your edits in the Inspector were saved. If you edited a part template's JSON directly, check for syntax errors. Try clicking a different element and then back to refresh the panel.

</details>

<details>

<summary>ProtoBot suggests a fix I do not understand</summary>

ProtoBot provides suggestions in the Review Comments section. If a suggestion is unclear, ask a follow-up question in the same thread. ProtoBot can explain its reasoning and offer alternative approaches.

</details>

<details>

<summary>I cannot find the right level shifter or adapter part</summary>

Search the Parts Bin for terms like "level shifter," "voltage translator," or "bus multiplexer." If nothing matches, create a **blank part** with the appropriate interfaces and configure it manually.

</details>

***

## Related pages

* [Validation (DRC)](/user-guide/validation-drc.md): understand DRC statuses and the Board Review panel
* [Connections & Compatibility](/user-guide/connections-and-compatibility.md): compatibility rules and connection setup
* [Parts: Add / Edit / Custom](/user-guide/parts-add-edit-custom.md): edit parts to resolve interface issues
* [Canvas Basics](/user-guide/canvas-basics.md): navigate to affected elements on the canvas


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.protoboard.xyz/user-guide/fixing-errors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.