document automation

Discover the top 10 use cases for Docassemble in the U.S. legal market and how Docassemble app development services streamline workflows and automation.

Ensure seamless operations with professional docassemble support services. Learn what a post-launch maintenance plan should include for courts and litigants.

Discover how docassemble court automation helps courts and self-represented litigants streamline document workflows. Learn what to automate first for efficiency.

Learn how docassemble document templates help create clean PDF and DOCX files with stable formatting, automation logic, and fewer document errors.

Introduction There’s a specific kind of frustration that only Docassemble developers know. You’ve spent hours crafting what feels like a perfectly logical interview. You hit run. And then — nothing. Or worse, something. An error message that reads like it was written specifically to confuse you, sitting there, judging your life choices. Docassemble debugging isn’t glamorous work, but it’s absolutely essential if you want to build legal automation tools that actually hold up in the real world. The good news? Most broken interviews fail for the same handful of reasons. Once you know where to look, fixing them gets a whole lot less painful. Let’s walk through everything — from YAML syntax crimes to logic loops that make your interview spin in circles. Why Docassemble Interviews Break Even When the Idea Is Simple Here’s something that trips up even experienced builders: Docassemble looks deceptively straightforward from the outside. Write some questions, define some variables, produce a document. Simple, right? Not quite. Docassemble runs on a powerful but unforgiving combination of YAML structure, Python logic, and Mako templating. When any one of these layers has an issue — even something as innocent as an extra space — the whole interview can grind to a halt. The reason simple ideas produce complex bugs usually comes down to three culprits: Understanding this distinction — that Docassemble has its own rules layered on top of standard YAML and Python — is the foundation of effective Docassemble troubleshooting. How Docassemble Reads YAML, Questions, Variables, and Logic Before you can fix a broken interview, you need a clear mental model of how Docassemble actually processes your file. Docassemble reads your YAML file as a collection of blocks. Each block serves a specific purpose — question blocks collect information, code blocks run Python logic, mandatory blocks define what the interview must accomplish, attachment blocks generate documents. The platform uses a dependency-driven interview engine. Instead of executing your interview top to bottom like a script, Docassemble looks at what it needs to produce and works backward to figure out what questions it needs to ask to get there. This is elegant — and it’s also the source of plenty of Docassemble interview logic bugs when developers assume sequential execution. When Docassemble encounters a variable it needs but hasn’t defined yet, it searches through your blocks to find a question or code block that can define it. If it can’t find one — or finds one it can’t execute — it throws an error. Simple as that. Painful as that. Common YAML Formatting Issues That Break Docassemble Interviews Let’s start with the crimes against YAML that show up constantly in Docassemble YAML errors. These are the bugs that make you feel like you’re losing your mind because the logic looks completely fine — it’s the formatting that’s the villain. Incorrect Indentation in YAML Blocks YAML is indentation-sensitive. Two spaces where there should be four, a misaligned list item, a sub-block at the wrong level — any of these will either throw an immediate parse error or, more dangerously, silently do something different from what you intended. Always use spaces, never tabs. Set your editor to visually distinguish indentation levels. This one habit alone eliminates a huge category of Docassemble YAML errors. Missing Colons, Dashes, or Quotation Marks YAML has strong opinions about colons and dashes. A missing colon after a key, a forgotten dash before a list item, or an unescaped special character in a string will break your block immediately. Pay particular attention to strings containing colons — YAML will interpret them as key-value separators unless you wrap the string in quotes. subquestion: This is fine: mostly will confuse the parser. subquestion: “This is fine: mostly” will not. Mixing Tabs and Spaces This deserves its own heading because it’s responsible for a disproportionate amount of developer suffering. Most text editors will happily mix tabs and spaces in ways that look identical on screen but cause YAML parsers to revolt. Configure your editor to convert tabs to spaces automatically. If you’re copying code from external sources — especially from PDFs or web pages — re-indent everything manually. Trust nothing that came from a format conversion. Wrong Placement of Code Blocks and Question Blocks Docassemble has specific expectations about block structure. A code block that tries to behave like a question block, or a mandatory block placed in a way that conflicts with dependency resolution, can produce errors that are maddeningly difficult to trace back to their source. When in doubt, check Docassemble’s official block hierarchy. Each block type has a specific role, and mixing responsibilities between blocks is a fast track to Docassemble error handling headaches. Common Logic Issues in Docassemble Interviews YAML syntax is only half the battle. Even with perfect formatting, broken logic can make your interview behave in ways that range from mildly annoying to completely nonfunctional. Undefined Variables That Stop the Interview Flow This is the most common logic error in Docassemble, full stop. Your interview references a variable — in a question, a code block, a template — that has never been defined anywhere in the YAML. Docassemble looks for a way to define it, can’t find one, and throws an Attribute has no ‘attribute’ or similar error. The fix seems obvious — define the variable — but the tricky part is that undefined variable errors often point to symptoms rather than causes. Trace the variable back to wherever it should originate and make sure that originating block actually executes before it’s needed. Circular Logic That Keeps Asking the Same Question Circular logic happens when Block A depends on Variable X, which is defined by Block B, which depends on Variable Y, which is defined by Block A. Docassemble gets caught in a loop, and your interview either crashes or behaves unpredictably. This is a classic problem in complex Docassemble interview logic involving conditional definitions. The solution is to map your variable dependencies explicitly before coding — a simple dependency diagram on paper