How do I troubleshoot documentation errors, and what is best practise for adding merge field tags to a document?

 Building Your Own Documentation: Best Practice & Common Errors

Introduction

This guide covers the most commonly encountered errors when self-service building or editing your own documentation in agentOS. It is not an exhaustive list of every possible error — it covers the issues we see most often. If you encounter an error not listed here, please contact support with the exact error message and the document you were working on.

Best Practice Before You Start

Following these steps will save you time and make it much easier to pinpoint the cause of any error, rather than troubleshooting a fully-built document with many changes at once.

• Build in small stages. Add merge field tags to one or two pages at a time rather than the whole document in one go.
• Test after each stage. Generate the document against a real tenancy after each round of changes, before adding more tags.
• Test against varied tenancy setups, not just a simple one, including:
  • A tenancy with multiple landlords
  • A tenancy with multiple tenants
  • A tenancy with one or more guarantors
• Testing this way means that if an error appears, you'll know it relates to the tags you just added, rather than searching through the entire document.

File Format Requirements

• Documents must be uploaded as genuine Microsoft Word (.docx) files.
• Files saved as .docx by non-Microsoft word processing software (e.g. Google Docs, LibreOffice, Pages, or various free/online converters) can appear identical on screen but save the underlying file structure slightly differently.
• This can cause the document to either fail to upload, or upload successfully but not generate/merge correctly.
• If you're experiencing upload or merge issues and the file wasn't created in Microsoft Word itself, this is the first thing to rule out. Re-saving or rebuilding the document in genuine Microsoft Word usually resolves it.

Common Errors

"Object reference not set to an instance of an object"

What it means: The document is trying to pull through a piece of data that doesn't exist for that particular tenancy or record.

Common self-service causes:

• A merge tag for a guarantor, second landlord, or second tenant has been added, but the tenancy you're testing against doesn't actually have one
• A repeating tag (multiple tenants, landlords, or guarantors) hasn't been placed inside a table, as required by the standard documentation guide — see that guide for correct table setup
• The tag references a field that isn't populated on that specific tenancy (e.g. a rent schedule tag on a tenancy where the rent schedule hasn't been fully set up)

How to resolve:

• Test the document against a tenancy that has all the data types you're trying to pull through (see Best Practice above)
• Check that any repeating tags are correctly placed inside a table, per the standard documentation guide
• If the error persists on a tenancy that does have the relevant data, contact support with the exact tenancy reference and the tag causing the issue

Repeating tags only pulling through the first entry (multiple tenants, landlords, guarantors)

What it means: The table structure is in place, but only the first tenant, landlord, or guarantor comes through, even though there are more on the tenancy.

Common self-service cause:

• Show/hide paragraph formatting has been used within or around the table. This prevents the table from repeating correctly, so it only outputs a single instance (the first entry) instead of replicating the row for each additional tenant, landlord, or guarantor.

How to resolve:

• Check the document for any show/hide paragraph formatting in or near the table containing the repeating tags
• Remove the show/hide formatting so the table can repeat as intended
• Retest against a tenancy with multiple tenants, landlords, or guarantors to confirm all entries now appear

Wrong document downloading

What it means: Generating a document for a tenancy produces a different document than the one you intended (e.g. the wrong letter, or a document meant for a different service type).

What causes it: The system selects which document to pull through based on a combination of tenancy type and service type, matched against the templates set up in System Letter Templates, under the Office tab. Where no template exists for that exact combination, the system falls back to the nearest matching template instead — which is often not the one you intended.

Common self-service cause:

• A mismatch between the tenancy type on the tenancy record and the tenancy type the template was built for. For example, a template built for an Assured Periodic Tenancy (APT) won't be picked up correctly if the tenancy is actually set up as an Assured Shorthold Tenancy (AST), or vice versa.

How to resolve:

• Check the tenancy type and service type on the tenancy record match what the template was set up for
• In System Letter Templates (Office tab), confirm a template exists for that exact tenancy type and service type combination
• If no exact match exists, either create one for that combination or adjust the tenancy record, rather than relying on the fallback template

Signable document opens with no signature sections

What it means: The document generates and downloads correctly, but when opened to sign, no signature fields appear for the signatories.

Common self-service cause:

• The wrong signable table structure has been used for the document type. There are two different structures:
  • The System Letter Template version of the signable table, intended for use with the standard system templates
  • An individual instance structure, which calls for specific named signatories and is intended for use in custom documents only
• Using the System Letter Template structure in a custom document (or the custom/individual structure in a system letter template) means the signable fields won't display, as the structure doesn't match what that document type expects.

How to resolve:

• Confirm whether your document is a System Letter Template or a custom document
• Check that the signable table structure used matches the correct type for that document (System Letter Template structure for system templates; individual instance structure for custom documents)
• If unsure which structure is currently in the document, contact support with the document name and we can confirm and correct it

Merge field tags returning as plain text (not merging at all)

What it means: The tag appears in the generated document exactly as typed (e.g. [Tenancy.TenantName]) instead of being replaced with the actual data.

Common self-service causes:

• The wrong tag set has been used for the document type. Different document types draw from different tag libraries, and tags from one type won't work in another:
  • Tenancy agreement templates use the standard tenancy agreement tags
  • Sales or letting brochures use the sales/letting brochure tag set
  • Custom documents use the person-type specific tags (e.g. tenant, landlord, guarantor specific tags), rather than the standard tenancy agreement set
• Tags are case-sensitive. If a tag is typed with the wrong capitalisation (for example using uppercase where the correct tag uses lowercase, or vice versa), it will not merge and will be returned as plain text, even if the rest of the tag is correct.

How to resolve:

• Confirm which document type you're building and check you're using the correct tag list for that type
• Cross-check the tag against the relevant tag guide rather than reusing tags copied from a different document type, and check the capitalisation matches exactly
• If the tag is confirmed correct for that document type and case, and still isn't merging, contact support with the document name and the specific tag

When to Contact Support

If you've followed the steps above and are still getting an error, or you encounter an error not covered in this guide, contact support with:

• The exact error message
• The document/template name
• The tenancy reference you tested against