Your Automation Will Break. Here's How to Build It So It Doesn't Take Everything Down

The Scenario Everyone Recognizes

A business hires a freelance automation consultant. The consultant builds something useful: a workflow in n8n or Make that syncs leads from a Facebook form into a CRM, sends a WhatsApp message, and notifies the team in Slack. Took three weeks to build. Works great.

Consultant gets paid and moves on.

Six months later something in the workflow stops working. Facebook changed an API field name. The CRM added a required field. The WhatsApp number format changed. Doesn't matter exactly what. The workflow just stops and nobody notices for four days because it fails silently.

Now the business owner goes back to the consultant. But they're busy with a new client, or they raised their rates, or they simply don't remember the specifics of a workflow they built eight months ago. And nobody internally can touch it because it's a black box.

This situation is common. Embarrassingly common. And it's almost never the fault of the automation breaking. It's a fault in how it was built.

Here's what makes the difference between an automation that's maintainable by anyone with moderate technical literacy and one that only the original builder can touch.

1. Name Everything Like You Won't Remember What It Does

When you build fast, you name nodes whatever the tool defaults to. "HTTP Request." "Set." "If." "Merge." After 15 nodes, the canvas looks like a flowchart made by someone who lost interest halfway through.

Every node and every scenario module should have a name that describes its purpose without any context. Not "HTTP Request 3" but "Fetch Lead Data from HubSpot CRM." Not "Set" but "Map Fields to Webhook Payload." Not "If" but "Check: Is Phone Number Present?"

The test for a good node name: can someone who has never seen this workflow read the name and understand what that node does without opening it? If the answer is no, rename it.

In Make, module names appear in the scenario view. In n8n, node names show in the canvas. Both support custom names. There is no reason not to use them.

For more complex workflows with branches, also add a sticky note on the canvas explaining the high-level logic. n8n has sticky notes built in. Make has scenario notes. Use them to write a two-paragraph plain-English explanation of what the workflow does and when it runs. This takes five minutes and will save hours later.

2. Inline Comments on Non-Obvious Logic

Node names tell you what a node does. Comments tell you why it does it that way.

Anything that looks weird, add a comment. "We check for the phone number here because HubSpot creates the contact before this workflow runs and sometimes the phone field is null for 30 seconds after creation. This 2-second delay before the check fixes it." That kind of thing. The original builder knows this because they spent two hours debugging it. Nobody else does.

In n8n, you can add descriptions to individual nodes. In Make, you can add notes to modules. Use both.

The comment doesn't need to be long. One or two sentences explaining the reasoning is enough. "Using field 'custom_15' instead of 'email' because the client's CRM was customized and email is stored there." That's it. Future you or future someone else will bless you for writing that.

3. Error Handling That Makes Noise

A workflow that fails silently is worse than a workflow that doesn't exist.

At least if the workflow doesn't exist, someone notices work isn't getting done. A silent failure keeps the appearance of automation running while nothing actually happens. Leads don't get contacted. Invoices don't get sent. Status updates don't reach the client. And nobody knows for three days.

Every workflow should have error handling that alerts a human immediately when something breaks.

In n8n: turn on error handling at the workflow level (Settings, Error Workflow). Create a separate error notification workflow that sends a Slack message or email with the workflow name, the error message, and a link to the failed execution. Every production workflow points to that error notification workflow.

In Make: add an error handler to each module that can fail (right-click on the module, Add Error Handler). The error route should end with a notification step, not just "ignore."

The Slack or email alert should include:

• Which workflow failed
• What the error message was
• When it happened
• A link to the execution log

That's enough for anyone to start diagnosing. Even a non-technical business owner can forward that alert to someone who can investigate.

4. Config Values in Environment Variables, Not Nodes

The most fragile workflows hardcode everything. The API key is pasted directly into the authentication field. The CRM account ID is typed into a node expression. The webhook URL the workflow calls is stored as a string inside a Set node.

When any of those values change, you have to open the workflow, find every place that value appears, and update it. If you forget one, the workflow breaks in a confusing way because two parts of it are using different values.

Environment variables solve this. Store config values in one place. Reference them everywhere.

In n8n: set environment variables in your deployment config (N8N_VARIABLES_ENABLED=true, then set variables via the UI or your .env file). Reference them in nodes with {{ $vars.MY_VARIABLE }}. The variable has one value, referenced in 12 places, and updating it requires changing it once.

In Make: use Data Stores or Constants for values that appear in multiple scenarios.

Specific things that should be environment variables, not hardcoded values:

• API keys and credentials (these especially)
• Account IDs, portal IDs, organization IDs
• Notification email addresses or Slack webhook URLs
• Any URL the workflow calls that could change
• Numeric thresholds used in filters (like "only proceed if deal value is above X")

That last one is underrated. When a business owner says "actually we want to change the threshold from 500 to 750," changing an environment variable takes 30 seconds. Finding where 500 is hardcoded in a 20-node workflow takes 20 minutes.

5. A Plain-English Runbook Doc for Every Workflow

Documentation sounds like extra work. It is, a little. But a runbook is not full documentation. It's a single page (or even half a page) that answers four questions:

1. What does this workflow do, in one sentence?
2. What triggers it and how often?
3. What should happen if it breaks (who to contact, where the logs are)?
4. What are the most common failure points and how to fix them?

Write this while you're building or right after you finish. It takes 15 minutes while the context is fresh. Finding that information 8 months later takes hours and involves checking Slack history and old emails.

Store the runbook somewhere obvious: a Notion page linked from the workflow's description, a Google Doc folder called "Workflow Docs," a README in the same repo as any custom code. Doesn't matter where, as long as it's findable.

One real example of the cost of not having this: a service business was running a daily invoice reminder workflow in Make. It started failing with a 401 error after their accounting software (FreshBooks) updated its OAuth flow. The person who built it was unreachable. It took a developer four hours to trace the problem, find the credential refresh logic, figure out the token storage, and fix it. A runbook that said "credentials stored in Make's FreshBooks connection, token refreshes automatically, but if you see 401 errors go to Make > Connections > FreshBooks and click Reauthorize" would have fixed it in seven minutes.

The Audit Checklist

If you've inherited an automation (or you want to check one you built a while ago), here's a list to work through:

Structure

• Every node/module has a descriptive name (not the tool's default)
• There's a sticky note or scenario description explaining the overall logic
• Branches are labeled (true/false, success/fail, match/no-match) not just arrows

Config

• No API keys or credentials hardcoded in node expressions or Set nodes
• No account IDs or portal IDs hardcoded in expressions
• All credentials are stored in the credential manager, not copied into node fields
• Threshold values and other config-y numbers are in variables, not hardcoded

Error handling

• An error handler exists and routes to a notification step
• Silent failures are impossible (at least for the main success path)
• The error alert includes enough context to diagnose without opening the workflow

Comments

• Any unusual logic has a comment explaining why
• Date format assumptions are commented (many broken workflows have "YYYY-MM-DD" hardcoded somewhere that turns out to need MM/DD/YYYY)
• Any workaround for an API quirk has a comment

Documentation

• A runbook exists with the four answers (what it does, what triggers it, who to call if broken, common failure points)
• The runbook is findable by someone who didn't build the workflow

A workflow that passes this checklist takes about the same amount of time to build as one that doesn't. Maybe 10-15% longer. The difference shows up 6 months later when something breaks and the person fixing it doesn't have to spend half a day figuring out what the original builder was thinking.

One More Thing: Version History

Both n8n and Make let you view workflow versions. In n8n, you can look at execution history. In Make, scenario version history is available in paid plans.

But version history is not a substitute for the practices above. Version history tells you what changed. It doesn't tell you why. Comments and documentation tell you why.

Keep old versions accessible. When something starts failing after a change, being able to diff the current version against the one that worked last week is useful. Don't delete old scenarios when you update them, archive them.

The maintainability problem in automation is not technical. The tools have everything you need to build something maintainable. The problem is habits, specifically whether the builder treats the workflow as a finished product or as a living system that someone else will need to understand and fix. Most of the practices above take five minutes to do and save hours to days later.

---

If you want us to build this for you, book a free workflow audit at airtective.com