> 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/reference/error-code-catalog.md). # Error Code Catalog Catalog of common DRC issues with causes, severity, and fix patterns for fast troubleshooting. This page is a quick-reference catalog of the most common Design Rule Check (DRC) issues you will encounter in Protoboard. For each issue you will find its severity, what causes it, and how to fix it. {% hint style="info" %} Protoboard does not use numeric error codes. Issues are identified by their **category and description** in Board Review. This catalog groups them by the underlying problem pattern so you can look up what you are seeing. {% endhint %} *** ## Connection Errors ### Protocol Type Mismatch | | | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Severity** | Error | | **State** | INCOMPATIBLE | | **Description** | Two interfaces are linked but their `protocol.type` values do not match. | | **Common Cause** | Manually linking an I2C interface to an SPI interface, or using a custom protocol name that does not match the other part. | | **Fix** | Remove the link and connect interfaces with matching protocol types. If the parts should be compatible, check whether one of them uses a non-standard protocol name (e.g., `"serial"` instead of `"uart"`) and update the definition. | ### Role Incompatibility | | | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Severity** | Error | | **State** | INCOMPATIBLE | | **Description** | Both sides of the link have the same role (e.g., both `master`) or roles that are not a recognized compatible pair. | | **Common Cause** | Connecting two microcontrollers via I2C where both are defined as `master`, or connecting two sensors that are both `slave`. | | **Fix** | One side must play the complementary role. For I2C, one part must be `master` and the other `slave`. For power, one must be `output` and the other `input`. Check the [role compatibility table](/reference/interfaces-and-harnesses.md#role-compatibility-pairs) for valid pairings. | ### Voltage Domain Mismatch | | | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Severity** | Error | | **State** | INCOMPATIBLE | | **Description** | The interface has `requires_matching_voltage_domain: true` but the power domains on each side have non-overlapping voltage ranges. | | **Common Cause** | Connecting a 3.3V-only sensor directly to a 12V logic output without level shifting. | | **Fix** | Either add a level shifter between the parts, power the sensor from a compatible voltage rail, or verify that the part definition's power domain ranges are correct. | *** ## Allocation Errors ### Missing Resource Allocation | | | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Severity** | Error | | **State** | PARTIALLY\_CONFIGURED or NOT\_CONFIGURED | | **Description** | An interface link exists but one or more required functions have no resource allocated to them. | | **Common Cause** | The harness was created and interfaces were linked, but resource allocation was not completed, either automatically (because no resource provides the needed function) or manually. | | **Fix** | Open the harness detail and allocate resources for each unbound function. If no suitable resource exists, the part definition may be missing a resource with that function name. | ### Resource Over-Allocation | | | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Severity** | Error | | **State** | INCOMPATIBLE | | **Description** | The same resource has been claimed by two or more exclusive interfaces simultaneously. | | **Common Cause** | A pin that serves as both I2C SDA and analog input is allocated to an I2C interface **and** an analog interface at the same time, but `shareable_with` does not allow this. | | **Fix** | Deallocate one of the conflicting interfaces and choose a different resource for it. If the resource genuinely supports both uses simultaneously, add `shareable_with` to the resource's function definitions. | ### Capacity Exceeded | | | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Severity** | Error | | **State** | INCOMPATIBLE | | **Description** | An interface instance has more connections than its `max_connections` constraint allows. | | **Common Cause** | Connecting 12 I2C slaves to a bus that has `max_connections: 8`, or daisy-chaining too many devices off a single power output. | | **Fix** | Reduce the number of connections to this interface instance. For I2C, split devices across multiple buses. For power, add additional power outputs or use a distribution board. | ### Max Instances Exceeded | | | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Severity** | Error | | **State** | INCOMPATIBLE | | **Description** | More interface instances have been created than the `max_instances` field allows. | | **Common Cause** | A microcontroller with `max_instances: 1` on its I2C master interface, but the design tries to create two I2C bus connections. | | **Fix** | Reduce the number of instances to the limit, or use a different part that supports more instances of the protocol. | *** ## Incomplete Configuration Warnings ### Unlinked Interface in Harness | | | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **Severity** | Warning | | **State** | NOT\_CONFIGURED | | **Description** | A harness exists between two parts but contains interface pairs that were discovered as compatible yet have not been linked. | | **Common Cause** | Auto-linking was not triggered, or the user explicitly chose not to link certain interfaces. | | **Fix** | Open the harness and review the available interface pairs. Link any that should be connected, or dismiss the warning if the unlinking is intentional. | ### Incomplete Function Linking | | | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Severity** | Warning | | **State** | PARTIALLY\_CONFIGURED | | **Description** | An interface link is active but not all of its required functions have been allocated to resources. | | **Common Cause** | An SPI interface requires MOSI, MISO, SCK, and SS, but only three of the four have been allocated, perhaps because the SS pin is already claimed by another interface. | | **Fix** | Complete the allocation by assigning resources to the remaining functions. If the needed resource is already taken, resolve the conflict first. | ### Unconnected Part | | | | ---------------- | ------------------------------------------------------------------------------------------------------------ | | **Severity** | Warning | | **State** | N/A (part-level) | | **Description** | A part is placed on the canvas but has no harnesses connecting it to any other part. | | **Common Cause** | The part was placed for planning purposes but has not been wired yet, or a harness was accidentally deleted. | | **Fix** | Connect the part to the relevant parts in your design, or remove it if it was placed in error. | *** ## Design Rule Violations ### Part Design Rule Triggered | | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Severity** | Warning (may escalate to Error for safety-critical rules) | | **State** | N/A (part-level) | | **Description** | A rule from the part's `design_rules` array is flagged based on the current configuration. | | **Examples** | "Maximum 40mA per I/O pin" when a high-draw device is connected to a GPIO. "VIN must be 7-12V when using external power" when the supply voltage range does not overlap. | | **Fix** | Review the design rule text and adjust your design accordingly. These rules come from the part's datasheet and represent real hardware limitations. | ### Power Budget Exceeded | | | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Severity** | Error | | **State** | N/A (part-level or board-level) | | **Description** | The total current draw from a power domain or power output exceeds its `max_current_mA` rating. | | **Common Cause** | Too many high-draw devices connected to a single regulated output (e.g., 6 servos on a 500 mA 5V rail). | | **Fix** | Reduce the load, add an external power supply, or use a power distribution board. Check each connected device's current requirements and ensure the sum stays within budget. | *** ## Quick Diagnosis Table | Symptom | Likely Issue | Where to Look | | ---------------------------------- | --------------------------------------------------------- | --------------------------- | | Red edge on canvas | INCOMPATIBLE link: protocol, role, or constraint mismatch | Board Review > Errors | | Yellow edge on canvas | PARTIALLY\_CONFIGURED: incomplete allocation | Harness detail panel | | Gray edge on canvas | NOT\_CONFIGURED: no allocation performed | Harness detail panel | | Part has error badge | Design rule or power budget violation | Board Review > By Part | | "No compatible interfaces" message | Protocol or role mismatch between parts | Check both part definitions | | Auto-link did not fire | Resources unavailable or already allocated | Check resource utilization | *** ## Troubleshooting Checklist {% stepper %} {% step %} #### Check protocol names Both interfaces must use the **exact same** `protocol.type` string. Common mistakes: `"serial"` vs `"uart"`, `"thread_adapter"` vs `"pneumatic"`. {% endstep %} {% step %} #### Check role compatibility Roles must form a recognized pair. Use the [compatibility table](/reference/interfaces-and-harnesses.md#role-compatibility-pairs) to verify. {% endstep %} {% step %} #### Check resource availability Each required function needs an **unallocated** resource providing that function. If all matching resources are already claimed, the allocation will fail. {% endstep %} {% step %} #### Check constraints Look at `max_connections`, `requires_matching_voltage_domain`, and any custom constraint fields. A single failed constraint makes the link INCOMPATIBLE. {% endstep %} {% step %} #### Check power domains If voltage domain matching is required, verify that the power domains on both sides have overlapping `voltage_range_V` values. {% endstep %} {% step %} #### Review Board Review output Open Board Review for the full error and warning list with specific harness, interface, and resource identification. {% endstep %} {% endstepper %} --- # 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/reference/error-code-catalog.md?ask=&goal= ``` `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.