Troubleshooting Guide

This page serves as a comprehensive troubleshooting guide, consolidating information from across Build a Doc documentation. Use this resource to diagnose and resolve common issues with document generation, templates, connectors, and integrations.

Quick Reference by Feature

Authentication & API Keys
Customer Portal
Power Platform Connectors
Power Automate Flows
Power Apps
Microsoft Teams Integration
Word Add-in
Template Errors
Document Actions
HTTP Status Codes
Network and Connection Errors
Retry Strategies

Authentication and API Keys

Key Not Working

Symptoms: Flow fails with authentication error

Solutions:

Verify the key was copied correctly (no extra spaces)
Check key status in customer portal (not revoked)
Verify subscription is active
Try creating a new key

See Generate an API Key for setup instructions.

Lost API Key

Problem: You’ve lost your API key

Solutions:

You cannot retrieve it - keys are never shown again after creation
Create a new key in the customer portal
Update your Power Automate connections
Revoke the lost key in the portal (if you know which one)

401 Unauthorised

Message: Invalid API key or API key not found

Causes:

API key is missing
API key is incorrect (typo or truncated)
API key has been revoked
Subscription has lapsed

Resolution Steps:

Copy API key directly from customer portal (don’t type manually)
Verify no extra spaces before or after the key
Confirm key is active in the portal
Check subscription is active
Create a new key if necessary

See Authenticate the Connector for detailed steps.

403 Forbidden - Feature Not Available

Message: Feature not available for your subscription

Causes:

Action requires higher tier plan
API key is valid but subscription lacks permission

Resolution:

Review your subscription plan features
Check your subscription plan in the portal
Upgrade plan if necessary

403 Forbidden - Quota Exceeded

Message: Monthly quota exceeded

Causes:

Document generation quota reached
API call limit reached

Resolution:

Wait for quota reset (next billing cycle)
Upgrade to higher plan
See Limits and Quotas for plan details

Customer Portal

Subscription Not Found

Problem: “Subscription not found” error when accessing portal

Cause: Signed in with wrong account

Solution: Sign out and sign in with the purchasing account

Page Stuck Loading

Problem: Portal page won’t load

Causes:

Cached authentication issue
Browser cache problems

Solutions:

Clear cookies
Use a private/incognito browser window
Try a different browser

Confirmation Email Not Received

Problem: Haven’t received activation email

Causes:

Marketplace processing delay
Email in spam folder

Solutions:

Wait up to 15 minutes
Check spam/junk folder
Contact support if still not received

Invalid or Expired Token

Problem: Token error when activating subscription

Causes:

Token missing or expired
Marketplace API error

Solutions:

Reopen the configuration link from the confirmation email
Retry later if marketplace API error
Contact support if persistent

Power Platform Connectors

Connection Failed

Symptoms: Cannot create or authenticate connector

Solutions:

Verify the API key is correct (no extra spaces)
Check that the API key is active in the customer portal
Try using a private/incognito browser window
Clear browser cache and cookies

See Configure the Power Platform Connector for setup instructions.

Connection Disappeared

Symptoms: Previously working connection no longer available

Solutions:

Check if the connection was deleted
Verify you’re signed in with the correct account
Re-create the connection if necessary

Connection Configuration Issues

Problem: Flow fails even with valid API key

Troubleshooting Checklist:

Check the flow run history and inspect the failing action’s error for HTTP status code and request ID
Confirm which connection the flow is using (connection dropdown inside the action)
Recreate the connection:
- Select a Build a Doc action
- Select ‘Change Connection’
- Click + Add new connection
- Paste the API key
- Save
If the error indicates rate limits, check your subscription quota/usage in the portal
If network errors appear, test connectivity from your environment to the Build a Doc API endpoints

Power Automate Flows

File Not Found / Permissions Error

Causes:

Wrong OneDrive file ID or file path
Incorrect SharePoint site URLs or file paths
Flow account lacks access
Insufficient read permissions

Solutions:

Re-select the file in the action to ensure correct file ID/path
Verify SharePoint site URLs and file paths are correct
Confirm the connected OneDrive account has permission to the file
Confirm Power Automate service account has read access to the document library
Use the file picker in SharePoint actions instead of manual paths

Trigger Not Firing

Causes:

Manual trigger not activated
Missing required inputs
Trigger phrase condition evaluating to false

Solutions:

Save the flow and run it using the Power Automate button (or the expected trigger)
Provide required manual-trigger inputs
Check condition logic for exact text matching
Consider case sensitivity (use toLower() for case-insensitive matching)
Check for extra whitespace in trigger phrases

Blank or Missing Fields in Output

Causes:

JSON keys don’t match template placeholders
Wrong data source name
Property name typo or casing error
Property doesn’t exist in data source

Solutions:

Make JSON property names exactly match template placeholders (case-sensitive)
Verify data source name matches template identifier exactly
Validate the payload structure using Compose or Parse JSON
Check tag names match JSON keys: use dot notation <<[Customer.Name]>> not <<[CustomerName]>>
Use Preview Templates with Sample Data to test

Wrong File Extension

Causes:

Create file filename is missing an extension
Using the wrong file type

Solutions:

Use .pdf for PDF output, .docx for Word output
Ensure file extension matches the Build a Doc action’s output format

Flow Completes But Output Missing

Causes:

File created in wrong location
Permissions issue on target location
Action succeeded but file creation step failed

Solutions:

Check flow run history for each action’s status
Verify target folder/library permissions
Confirm “Create file” action shows success
Check the correct document library/folder

Power Apps

Connector / Action Not Listed in Formula Bar

Causes:

The data source isn’t added to the app
Editor didn’t recognise the connector

Solutions:

Open the Data panel and confirm the connector is present (e.g., HappyWiredPowerDocs)
If missing, remove and re-add the data source
Re-open the app editor to force a refresh
Re-check the formula bar after re-adding

ParseJSON Errors

Causes:

Invalid JSON string
Unescaped double quotes
Malformed structure

Solutions:

Validate the JSON string using an online/IDE JSON validator
Store the JSON in a Text input to inspect it
Escape double quotes inside strings as required
Only call ParseJSON() when the string is valid

Output Variable Is Blank or Missing Result

Causes:

Compute action failed
Connector response shape different than expected
Value nested deeper than expected

Solutions:

Confirm the action succeeded (no runtime error)
Set a temporary label to JSON(Output) to inspect the actual response shape
Compare debug output to your label formula
Check if value is nested (e.g., Output.body.Result vs Output.result)

Microsoft Teams Integration

Teams Message Won’t Post

Causes:

Channel is private without Flow Bot access
Missing permissions
Incorrect channel configuration

Solutions:

Verify the channel is public (private channels require explicit Flow Bot access)
Confirm Teams connector has channel posting permissions
Add the Flow Bot to private channels manually if needed
Check the Teams action isn’t nested incorrectly within a condition

Trigger Phrase Not Detected

Causes:

Condition logic too strict
Case sensitivity issues
Extra whitespace

Solutions:

Check condition logic for exact text matching
Use debugging (Compose actions) to inspect message content
Consider whitespace and special characters
Use toLower() for case-insensitive matching

Adaptive Card Not Rendering

Causes:

Invalid JSON structure
Unsupported field types
Formatting issues

Solutions:

Validate JSON structure in the adaptive card payload
Test card in Teams App Studio before deploying
Check for unsupported field types or formatting

See Integrate with Microsoft Teams and Automate Document Generation with Teams for detailed setup.

Word Add-in

Add-in Not Loading

Symptoms: Add-in won’t start or displays error

Solutions:

Restart Microsoft Word
Clear the Office cache
Ensure you have a stable internet connection
Check compatibility requirements
Verify Word version is supported

Installation Issues

Problem: Cannot find or install the Add-in

Steps to Install:

Open Microsoft Word
On the Home Ribbon, go to Insert → Get Add-ins
Search for “Build a Doc”
Click Add to install

See Author Advanced Word Templates for detailed installation instructions.

Preview Generation Failed

Message: Preview generation failed

Common Causes:

Template syntax errors
Invalid data source
Missing or null values
Data format mismatch
Wrong data format (Word Add-in requires array format)

Resolution:

Enable inline error display to see specific errors
Verify template syntax with examples
Validate data source using Preview Templates with Sample Data
Check data types and structure
Ensure data is in array format: [{ }] not object format { }
See Debug Template Validation Errors for detailed troubleshooting

Blank Placeholders in Preview

Cause: JSON property path doesn’t match template

Solutions:

Verify paths match exactly (case-sensitive)
Check for typos in property names
Ensure nested paths use correct dot notation

JSON Validation Errors

Cause: Invalid JSON syntax in sample data

Solutions:

Use a JSON validator/formatter tool
Remove trailing commas
Use double quotes, not single quotes
Ensure all brackets { }, [ ] are closed

Template Errors

Common Template Syntax Errors

Error	Cause	Example	Fix
Unexpected end of tag	Missing `>>`	`<<[CustomerName]>`	`<<[CustomerName]>>`
Unclosed foreach block	Missing `<</foreach>>`	`<<foreach [item in Items]>>`	Add `<</foreach>>`
Unclosed if block	Missing `<</if>>`	`<<if [ShowDiscount]>>`	Add `<</if>>`
Invalid path	Property doesn’t exist or typo	`<<[Customer.Name]>>`	Check spelling and data structure
Type mismatch	Wrong data type for operation	Using string in math operation	Verify data types match expected format

Quick Fix Reference

Problem	✅ Solution
Tag doesn’t match JSON	Use dot notation: `<<[Customer.Name]>>`
Loop doesn’t close	Always add `<</foreach>>`
Wrong case	Match JSON exactly: `Customer` ≠ `customer`
Syntax error	Use format: `<<[Field]>>`

Data Binding Errors

Error: Template expressions fail or return null

Common Causes:

Property name typo or casing error (case-sensitive)
Property doesn’t exist in data source
Data structure mismatch
Null or missing values

Resolution:

Verify property names match data source exactly (case-sensitive)
Check data source structure using templates with real data
Handle null/missing values with safe access operator: <<[Customer?.Email]>>
Use inline error display to see where errors occur
Preview template with the Word Add-in before deployment

Enabling Inline Error Display

Enable “Inline template syntax errors” in the Build a Doc action:

Errors appear in the output document instead of failing the action
Helps identify exactly where errors occur
Useful during template development
Should be disabled in production

See Debug Template Validation Errors for detailed instructions.

Template Processing Timeouts

Message: Request timed out

Causes:

Document too large
Complex template processing (many expressions, loops)
High-resolution images
Large data volumes
High service load

Resolution:

Reduce document complexity
Split large documents into smaller batches
Reduce image resolution
Simplify template logic if possible
Test with actual data volumes expected in production
Retry at different time
See Scalability and Performance for optimisation tips

Production Template Issues

Problem: Template works in development but fails in production

Common Issues:

Issue	Cause	Solution
Blank or missing placeholders	JSON keys don’t match template expressions or wrong data source name	Verify data source name matches template identifier exactly (case-sensitive). Confirm all property paths exist in JSON structure.
File not found error	Incorrect file path or insufficient read permissions	Verify the template file path is correct in the “Get file content” action. Confirm Power Automate service account has read access to the document library.
Unexpected output formatting	Template was modified without retesting or data format changed	Test the template with representative data in the Word Add-in. Verify data source structure hasn’t changed since template creation.
Generation timeout or slow performance	Complex template with many expressions or large data volumes	Simplify template logic if possible. Consider splitting complex templates into smaller, focused ones. Test with actual data volumes expected in production.
Syntax or expression errors	Template contains invalid expressions or malformed tags	Enable “Inline template syntax errors” in Power Automate flow to see errors in output. Review and fix template using Word Add-in.

Debug Production Issues:

Check Power Automate error messages - These indicate template syntax or data binding issues
Test with the same data - Reproduce the issue using the exact data that caused the failure
Use Word Add-in preview - Test the problematic template with sample data
Review recent changes - Check if recent template modifications may have caused the issue
Consult template documentation - Verify the data structure hasn’t deviated from template requirements

See Publishing Templates to Production for best practices.

Document Actions

Document Invalid or Corrupted

Message: Document is invalid or corrupted

Common Causes:

File is corrupted
File is not the declared format
File is password-protected
File format not supported
File is truncated or incomplete

Resolution:

Verify file opens correctly locally
Ensure correct file format
Remove password protection
Provide the complete file binary or base64
Verify payload decodes to a valid file

Password-Protected Files

Problem: Cannot process password-protected or encrypted files

Causes:

File requires password to open
File has editing restrictions
File has permission restrictions

Solutions:

Supply an unprotected copy of the file
Remove password protection prior to processing
Remove encryption or restrictions before conversion
Use an unencrypted copy with modification permissions

Convert Excel Document

Problem: Conversion fails

Common Issues:

Issue	Cause	Solution
Invalid or missing document payload	Document input is empty, truncated, or not valid binary	Provide complete workbook binary/base64 and validate it decodes
Unsupported output format	Output format string is misspelled	Verify exact format name (e.g., `.pdf`, `.csv`, `.xlsx`)
Named worksheets not found	Worksheet names don’t match (case or spelling mismatch)	Use exact worksheet names, ensure they match

Convert Word Document

Common Issues:

Issue	Cause	Solution
Document missing, truncated, invalid	Document input is empty, corrupted, not valid	Ensure complete `.doc`/`.docx` binary, verify opens locally
Unsupported output format	Output format value is incorrect	Confirm format matches supported value (case-sensitive)
Password-protected document	Word file is encrypted or protected for editing	Provide unprotected copy or remove restrictions

Convert PowerPoint Document

Common Issues:

Issue	Cause	Solution
Document missing, truncated, invalid	Input is empty, truncated, not valid	Provide full presentation binary/base64
Unsupported output format	Output format value is incorrect	Confirm format exactly matches supported values
Password-protected presentation	File requires password or is encrypted	Supply unprotected copy of presentation

Convert PDF Document

Common Issues:

Issue	Cause	Solution
Document missing, truncated, invalid	PDF input is empty, corrupted	Provide full PDF base64 and verify it decodes to valid PDF
Unsupported output format	Output format string is incorrect	Verify format value exactly matches supported strings
Password-protected PDF	PDF is encrypted or requires password	Supply unencrypted copy or remove password protection

Convert Visio Document

Common Issues:

Issue	Cause	Solution
Document missing, truncated, invalid	Document input is empty, corrupted	Supply complete `.vsdx`/`.vsd` binary/base64 payload
Unsupported output format	Output format is incorrect	Verify format string exactly matches supported value
Page index out of range	Requested page exceeds document’s page count	Use zero-based page index, ensure within page range

Convert OneNote Document

Common Issues:

Issue	Cause	Solution
Document missing or invalid	Document input is empty, truncated	Provide complete `.one` binary/base64 payload
Unsupported output format	Output format string is incorrect	Confirm format name is exactly one of supported values
Password-protected OneNote file	File is encrypted or requires password	Supply unprotected copy or remove password protection

Convert HTML

Common Issues:

Issue	Cause	Solution
HTML input invalid or malformed	HTML contains syntax errors, unclosed tags	Validate and sanitise HTML, correct template expression syntax
URL unreachable	URL not publicly accessible or requires authentication	Use publicly accessible URL or supply raw HTML string
Template expressions fail	Template references absent or mis-named keys	Verify data sources keys match template identifiers (case-sensitive)

Extract PDF Data

Common Issues:

Issue	Cause	Solution
Document missing, truncated, invalid	PDF input is empty, truncated	Provide complete PDF binary/base64 payload
No form fields returned	PDF has no interactive form fields or flattened	Confirm PDF contains interactive fields, not flattened
Form fields empty	Fields present but values are empty or default	Verify form was filled out, check field names and types

Update PDF Data

Common Issues:

Issue	Cause	Solution
Document missing, truncated, invalid	Document payload is empty, truncated	Provide complete PDF binary or base64
PDF is password-protected or encrypted	Encryption prevents modifications	Use unencrypted copy with modification permissions

Merge Word Documents

Common Issues:

Issue	Cause	Solution
Missing, truncated, invalid input	Source/destination payload is empty	Provide full `.doc`/`.docx` binary or base64 for both documents
Unsupported merge method	Merge method value is invalid	Use exactly `Append`, `ReplaceBookmark`, or `ReplaceText`

Merge PowerPoint Presentation

Common Issues:

Issue	Cause	Solution
Missing, truncated, invalid input	Source/destination payload is empty	Provide full `.ppt`/`.pptx` binary for both inputs
Unsupported merge method	Merge method value is invalid	Use exactly `Append` or `Slide Position` (case sensitive)

Format PowerPoint Presentation

Common Issues:

Issue	Cause	Solution
Document missing, truncated, invalid	Document input is empty, truncated	Provide complete presentation binary/base64
Colour keys not recognised	Colour scheme keys don’t match expected names	Use canonical scheme key strings exactly

Render Excel Chart

Common Issues:

Issue	Cause	Solution
Document missing, truncated, invalid	Workbook payload is empty, truncated	Supply full workbook binary or base64
Worksheet not found	Worksheet name doesn’t match (case/spelling)	Verify exact worksheet name (case-sensitive)

Compute Data

Common Issues:

Issue	Cause	Solution
Data is empty or not an array	Data input is missing, null, or not an array	Ensure data is supplied and is an array of objects
Filter syntax invalid	Filter expression contains invalid syntax	Validate expression syntax and property names
Expression syntax invalid	Expression contains malformed syntax	Ensure expression uses exactly one aggregate function when needed

Compare Word Documents

Common Issues:

Issue	Cause	Solution
File content missing or invalid	First/second document input is empty	Ensure both inputs contain complete `.doc`/`.docx` binary
Unsupported file type	Input is not a Word file	Use `.docx` (preferred) or `.doc` files
Password-protected documents	One or both files are encrypted	Supply unprotected copies

HTTP Status Codes

Client Errors (4xx)

Code	Name	Description	Resolution
400	Bad Request	Invalid request format or parameters	Check template syntax and data format
401	Unauthorised	Invalid or missing API key	Verify API key is correct and active
403	Forbidden	Subscription lacks permission or quota exceeded	Check subscription plan/features
404	Not Found	Resource or action not found	Verify action name and parameters
429	Too Many Requests	Rate limit exceeded	Reduce request frequency; implement backoff

Server Errors (5xx)

Code	Name	Description	Resolution
500	Internal Server Error	Unexpected server error	Retry; contact support if persistent
502	Bad Gateway	Gateway/proxy error	Retry after brief delay
503	Service Unavailable	Service temporarily unavailable	Retry with exponential backoff
504	Gateway Timeout	Request timed out	Retry; consider smaller documents

Rate Limiting (429)

Message: Rate limit exceeded. Retry after X seconds

Causes:

Too many requests in short time period
Burst limit exceeded
Exceeding subscription tier limits

Resolution:

Implement retry logic with exponential backoff
Add delays between requests
Consider batch processing at lower rate
Upgrade plan for higher limits

See Scalability and Performance for best practices.

Network and Connection Errors

Network/CORS Errors

Message: Connection refused or Network error

Causes:

Network or proxy blocking outbound requests to Build a Doc endpoints
Corporate firewall restrictions
DNS resolution issues

Resolution:

Whitelist the connector endpoints
Work with your network admin
Verify HTTPS access to Build a Doc services
Test connectivity from your environment to Build a Doc API endpoints

Data Source Format Errors

Message: Invalid data source format or JSON/XML/CSV syntax error

Causes:

JSON/XML/CSV syntax error
Mismatched data source format declaration
Invalid JSON (trailing commas, single quotes)

Resolution:

Validate data source format syntax
Ensure format declaration matches actual format
Remove trailing commas
Use double quotes, not single quotes
Ensure all brackets { }, [ ], < > are closed
Use Preview Templates with Sample Data to test data

Retry Strategies

When to Retry

Error Type	Should Retry	Strategy
429 Rate Limit	Yes	Exponential backoff
500 Server Error	Yes	Fixed delay, limited attempts
502/503 Gateway	Yes	Exponential backoff
504 Gateway Timeout	Yes	Exponential backoff
400 Bad Request	No	Fix input and resubmit
401 Unauthorised	No	Fix API key
403 Forbidden	No	Check subscription/permissions
Template Error	No	Fix template

Exponential Backoff

For transient errors, use exponential backoff:

First retry: Wait 1 second
Second retry: Wait 2 seconds
Third retry: Wait 4 seconds
Fourth retry: Wait 8 seconds
Fifth retry: Wait 16 seconds
Give up after 5 attempts

This gives the service time to recover while preventing overwhelming it with repeated requests.

Power Automate Error Handling

Configure Run After:

Power Automate’s “Configure run after” feature lets you control when actions execute based on previous action outcomes.

Setup:

Add a parallel branch after the Build a Doc action
Click the … menu → Configure run after
Select conditions: is successful, has failed, is skipped, has timed out

Scope for Try-Catch:

Use Scope actions to group related actions and handle errors at the group level.

Pattern:

Scope: Try
├── Build a Doc Action
├── Create File
└── Send Email

Scope: Catch (Configure run after: has failed)
├── Compose: Error details
├── Send email: Error notification
└── Terminate: Failed

See Handle Errors in Flows for complete instructions with examples.

Error Handling Best Practices

Validate inputs - Check template and data before calling action
Enable inline errors - Enable during development for easier debugging
Implement retries - Handle transient failures gracefully with exponential backoff
Log errors - Record error details for troubleshooting and audit trail
Notify on failure - Alert appropriate parties when errors occur
Test edge cases - Verify behaviour with missing data, empty arrays, etc.

Troubleshooting Guide

Quick Reference by Feature

Authentication and API Keys

Key Not Working

Lost API Key

401 Unauthorised

403 Forbidden - Feature Not Available

403 Forbidden - Quota Exceeded

Customer Portal

Subscription Not Found

Page Stuck Loading

Confirmation Email Not Received

Invalid or Expired Token

Power Platform Connectors

Connection Failed

Connection Disappeared

Connection Configuration Issues

Power Automate Flows

File Not Found / Permissions Error

Trigger Not Firing

Blank or Missing Fields in Output

Wrong File Extension

Flow Completes But Output Missing

Power Apps

Connector / Action Not Listed in Formula Bar

ParseJSON Errors

Output Variable Is Blank or Missing Result

Microsoft Teams Integration

Teams Message Won’t Post

Trigger Phrase Not Detected

Adaptive Card Not Rendering

Word Add-in

Add-in Not Loading

Installation Issues

Preview Generation Failed

Blank Placeholders in Preview

JSON Validation Errors

Template Errors

Common Template Syntax Errors

Quick Fix Reference

Data Binding Errors

Enabling Inline Error Display

Template Processing Timeouts

Production Template Issues

Document Actions

Document Invalid or Corrupted

Password-Protected Files

Convert Excel Document

Convert Word Document

Convert PowerPoint Document

Convert PDF Document

Convert Visio Document

Convert OneNote Document

Convert HTML

Extract PDF Data

Update PDF Data

Merge Word Documents

Merge PowerPoint Presentation

Format PowerPoint Presentation

Render Excel Chart

Compute Data

Compare Word Documents

HTTP Status Codes

Client Errors (4xx)

Server Errors (5xx)

Rate Limiting (429)

Network and Connection Errors

Network/CORS Errors

Data Source Format Errors

Retry Strategies

When to Retry

Exponential Backoff

Power Automate Error Handling

Error Handling Best Practices

Related Topics