A developer I was mentoring once spent an entire afternoon debugging what turned out to be a simple context confusion error — attempting to call a main-context-only function from within UI context code — that, once correctly diagnosed, took only minutes to actually fix, illustrating how much debugging time genuinely comes down to correctly identifying which error category you are actually facing rather than the eventual fix itself being complex.
Category One: Context Confusion Errors
As covered in detail in our plugin development guide, the separation between main context and UI context is fundamental to Figma’s plugin architecture, and a significant portion of beginner debugging time, exactly like my mentee’s afternoon-long session, traces back to attempting operations in the wrong context.
Recognizing this error category: Error messages mentioning that a specific function or API is not available, particularly when you are confident you are using correct API syntax, often indicates you are attempting to call a main-context-specific function from UI context code, or vice versa, rather than an actual syntax or logic error in how you are calling that function.
The fix: Verify which context your problematic code is actually running in, and confirm whether the specific function or API you are attempting to use is actually available in that particular context, restructuring your code to use the message-passing system to request the operation from the correct context if you have confirmed this context mismatch is indeed the issue.
Category Two: Asynchronous Operation Handling Errors
Many Figma API operations are asynchronous, returning promises rather than immediate synchronous results, and errors stemming from not properly awaiting or handling these asynchronous operations represent another genuinely common error category.
Recognizing this error category: Code that appears to execute without throwing an explicit error, but produces unexpected results — operations seeming to not have actually completed, or subsequent code executing before an expected prior operation has genuinely finished — often points toward improper asynchronous handling rather than a more obvious explicit error message pointing directly at the actual underlying cause.
The fix: Carefully review whether each Figma API call that returns a promise is being properly awaited (using async/await syntax, or proper promise chaining) before your code proceeds to depend on that operation’s completed result, rather than assuming synchronous execution order for operations that are actually asynchronous.
Category Three: Manifest Configuration Errors
As mentioned in our plugin development guide, manifest misconfiguration can cause confusing downstream errors that do not always clearly point back to the actual manifest-level root cause.
Recognizing this error category: Errors suggesting your plugin cannot find expected files, or unexpected behavior that does not match what your actual code appears to specify, sometimes traces back to manifest file references not correctly pointing to your actual current file structure, particularly after any reorganization of your project’s file layout that was not correspondingly updated within the manifest configuration.
The fix: Carefully verify your manifest file’s specified paths and references genuinely match your actual current project file structure, rather than assuming the manifest remains correct simply because it worked correctly at some earlier point before subsequent project reorganization.
Category Four: Selection and Node Type Assumption Errors
Code that assumes a specific node type (assuming a selected element is specifically a frame, for example, when it might actually be a different node type like a group or component instance) without actually verifying this assumption can produce errors when that assumption turns out incorrect for some specific document or selection scenario.
Recognizing this error category: Errors specifically occurring only with certain documents or selections, while working fine with others, often indicates an unverified type assumption that happens to hold true for your typical testing scenarios but breaks for some specific document structure or selection type your testing did not happen to cover.
The fix: Add explicit type checking before assuming a specific node type, handling the case where your assumption does not hold true gracefully, rather than allowing your code to simply fail when encountering a node type your initial assumption did not account for.
Category Five: Permission and Manifest Capability Mismatches
If your plugin attempts an operation requiring a specific permission or capability not declared in your manifest (network requests, for example, if your manifest does not include appropriate network access declaration), this produces errors specifically related to this permission mismatch.
Recognizing this error category: Errors specifically related to network requests, certain API access, or similar capability-gated functionality, particularly if you have recently added new functionality without correspondingly reviewing whether your manifest’s declared permissions still adequately cover this new functionality’s actual requirements.
The fix: Review your manifest’s declared permissions against your plugin’s actual current functionality requirements, adding any newly required permission declarations that your expanded functionality now requires but that your original manifest configuration did not yet account for.
A General Debugging Sequence
When facing an unclear plugin error, working through these categories in this general sequence, since it moves from genuinely most common to progressively less common causes based on my own extensive debugging experience across many plugin development projects, helps systematically narrow down the actual cause rather than randomly guessing across possible explanations.
First, check whether the problematic code might be running in the wrong context, given how common this specific confusion is, especially for newer plugin developers.
Second, if context seems correct, check for improper asynchronous operation handling, particularly if errors are not explicit but rather manifest as unexpected timing or incomplete-seeming results.
Third, verify manifest configuration matches your actual current project structure, particularly after any recent file reorganization.
Fourth, check for unverified node type assumptions if errors seem specific to certain documents or selections rather than occurring universally.
Fifth, review permission declarations against actual functionality requirements, particularly for any recently added features.
Using Console Logging Effectively for Diagnosis
Beyond this categorical framework, liberal use of console logging at various points in your code, specifically logging variable values and confirming which code paths are actually executing, helps narrow down where within your code an issue is actually occurring, which combined with the categorical framework above, helps you both locate where a problem occurs and correctly categorize what kind of problem it actually represents.
A Quick Reference Error Category Summary
| Category | Key Symptom | Primary Fix |
|---|---|---|
| Context confusion | Function/API unavailable despite correct syntax | Verify and correct which context code runs in |
| Async handling | Unexpected results without explicit error | Properly await/handle promise-based operations |
| Manifest configuration | File-not-found or structure mismatch errors | Verify manifest paths match actual project structure |
| Node type assumptions | Errors specific to certain documents/selections | Add explicit type checking before assumptions |
| Permission mismatches | Errors around specific capability-gated operations | Review and update manifest permission declarations |
What I Told My Mentee After the Afternoon-Long Session
I walked through this categorical framework, showing how the specific error they had spent hours on actually matched the context confusion category’s typical symptoms quite clearly, once viewed through this lens rather than approached as an unfamiliar, unprecedented problem requiring fresh first-principles debugging each time.
Adopting this categorical recognition approach, checking against these common categories before assuming any new error represents some entirely novel problem, considerably reduced their subsequent debugging time on later issues, since most plugin development errors, in my own extensive experience, genuinely do fall into this relatively small number of recurring categories rather than representing endless unique problems each requiring entirely fresh diagnostic approaches.
What specific error or unexpected behavior are you currently encountering? Describe the symptom and I can help you identify which category it likely falls into.