Connection Issues

This guide covers common connection problems in Zenmako and how to resolve them.

Connection Test Failing

When you test a connection and it fails, the issue typically falls into one of these categories.

Invalid Credentials

Symptoms:
  • "Invalid credentials" or "Authentication failed" error
  • "Unauthorized" (401) response
  • "Invalid API key" message
    • Solutions:
  • Expired Token: OAuth tokens expire after a period of time. Go to the connection settings and click "Reconnect" to generate a new token.
  • Wrong API Key: Double-check that you copied the entire API key without extra spaces. Some services have multiple keys (test vs. production) - ensure you're using the correct one.
  • Revoked Credentials: If you regenerated your API key in the external service, the old key stored in Zenmako is now invalid. Update the connection with the new key.
  • Environment Mismatch: Some services (like Stripe) have separate test and production environments. Verify you're using credentials for the correct environment.

    • Wrong Server or Domain

    Symptoms:
  • "Could not connect to server" error
  • Connection timeout
  • "Host not found" error
    • Solutions:
  • Self-Hosted Instances: If you're connecting to a self-hosted service (Jira Server, GitLab self-managed), verify the URL is correct and includes the protocol (https://).
  • Regional Endpoints: Some services have regional URLs (e.g., api.eu.service.com vs api.us.service.com). Use the endpoint that matches your account region.
  • Subdomain Errors: For services like Slack or Notion workspaces, ensure you're using the correct workspace/subdomain identifier.

    • Network Issues

    Symptoms:
  • Intermittent connection failures
  • Timeout errors
  • "Network unreachable" messages
    • Solutions:
  • Firewall Rules: If you're in a corporate environment, ensure your firewall allows outbound connections to the service's API endpoints.
  • VPN Interference: Some VPNs can block or interfere with API connections. Try testing without the VPN if applicable.
  • Service Outage: Check the external service's status page. If they're experiencing an outage, wait and retry later.

    • Authentication Errors

    Token Expired

    Symptoms:
  • "Token expired" error
  • "Refresh token invalid" message
  • Connection worked before but suddenly fails
    • How to Refresh:
  • Navigate to Settings > Connections
  • Find the affected connection
  • Click the Reconnect button
  • Complete the OAuth flow again
  • Test the connection to verify it works
    • Note: Zenmako automatically refreshes tokens when possible. If automatic refresh fails, it usually means the refresh token itself has expired (typically after 30-90 days of inactivity, depending on the service).

    Insufficient Permissions or Scopes

    Symptoms:
  • "Forbidden" (403) error
  • "Insufficient permissions" message
  • Connection works but specific actions fail
    • Solutions:
  • Review Required Scopes: Check the Zenmako documentation for your connector to see which permissions/scopes are required.
  • Reconnect with Correct Scopes: Disconnect and reconnect the service. During the OAuth flow, ensure you grant all requested permissions.
  • Admin Approval Required: Some enterprise services require an administrator to approve the OAuth application before users can connect. Contact your IT administrator.
  • Role-Based Access: Your account in the external service may not have permission to access certain resources. Verify your role has the necessary access.

    • Account Access Revoked

    Symptoms:
  • "Access revoked" error
  • "Application not authorized" message
  • Previously working connection now fails
    • Solutions:
  • Re-authorize the Application: Go to the external service's settings (usually under "Connected Apps" or "Integrations") and check if Zenmako was removed. Reconnect through Zenmako to re-authorize.
  • Account Deactivated: If your account in the external service was deactivated or suspended, the connection will fail. Resolve the account issue with that service first.
  • Organization Policy Change: Enterprise administrators may have revoked access to third-party applications. Contact your administrator.

    • "Not Found" Errors

    Resource Not Shared with Integration

    Symptoms:
  • "Page not found" or "Resource not found" error
  • Can see the resource in the external service but Zenmako cannot access it
  • Works for some resources but not others
    • This is especially common with Notion, where pages must be explicitly shared with the integration. Solutions:
  • Notion: Open the page in Notion, click the "..." menu in the top right, select "Connections", and add the Zenmako integration. Child pages inherit permissions, so sharing a parent page shares all its subpages.
  • Google Drive: Ensure the file or folder is shared with the service account email or the connected Google account has access.
  • Confluence: Verify the connected user has "View" permission on the space or page.
  • General: Most services require the authenticated user to have explicit access to resources. Verify your account can view the resource directly in that service.

    • Wrong Resource IDs

    Symptoms:
  • "Not found" error when accessing a specific resource
  • ID-based lookups fail
    • Solutions:
  • Verify the ID: Resource IDs can be found in the URL when viewing the resource in the external service. Copy it directly rather than typing it manually.
  • ID Format: Some services use different ID formats in different contexts (e.g., numeric vs. alphanumeric). Use the format specified in Zenmako's documentation.
  • Workspace/Project Prefix: Some IDs require a workspace or project prefix (e.g., PROJ-123 instead of just 123).

    • Deleted Resources

    Symptoms:
  • Resource previously accessible but now returns "Not found"
  • References to resources that no longer exist
    • Solutions:
  • Check Trash: The resource may be in the service's trash. Restore it or update your Zenmako configuration to reference a different resource.
  • Archived Items: Some services archive rather than delete. Check if the resource was archived and restore it if needed.
  • Update References: If the resource was intentionally deleted, update your Zenmako workflows to reference the correct replacement resource.

    • Rate Limiting

    What It Means

    Rate limiting occurs when you make too many API requests to an external service in a short period. Services impose these limits to ensure fair usage and system stability.

    Symptoms:
  • "Too many requests" (429) error
  • "Rate limit exceeded" message
  • Requests work sometimes but fail during high activity

    • How Zenmako Handles It

    Zenmako includes built-in rate limit handling:

  • Automatic Retry: When a rate limit is hit, Zenmako automatically waits and retries the request.
  • Exponential Backoff: Retry delays increase progressively to avoid hitting the limit again immediately.
  • Request Queuing: Requests are queued and processed at a sustainable rate.

    • What You Can Do

  • Reduce Frequency: If running scheduled workflows, increase the interval between runs.
  • Batch Operations: Where possible, use batch endpoints rather than making many individual requests.
  • Optimize Queries: Use filters to reduce the amount of data retrieved. Fetching only what you need reduces API calls.
  • Check Service Limits: Review the external service's rate limit documentation. Some services offer higher limits on paid plans.
  • Spread the Load: If you have multiple workflows hitting the same service, stagger their execution times.

    • Data Not Appearing

    Knowledge Base Not Updated

    Symptoms:
  • Recent changes in the external service don't appear in Zenmako
  • Search results show outdated information
  • New resources aren't visible
    • Solutions:
  • Trigger Manual Sync: Go to the connection settings and click "Sync Now" to force an immediate update.
  • Check Sync Status: Look for any sync errors in the connection details. A failed sync means data wasn't updated.
  • Wait for Scheduled Sync: Zenmako syncs data periodically. Recent changes may not appear until the next scheduled sync completes.
  • Verify Connection is Active: Ensure the connection is still valid and hasn't encountered authentication errors that would prevent syncing.

    • Permissions on Specific Resources

    Symptoms:
  • Some data appears but other expected data is missing
  • Partial results from queries
    • Solutions:
  • Check Resource-Level Permissions: Even with a valid connection, individual resources may have restricted access. Verify the connected account can access the missing resources directly in the external service.
  • Inherited Permissions: Some services (like Notion) require explicit sharing with integrations. Parent containers may be shared but specific items might not be.
  • Team/Workspace Boundaries: The connected account may only have access to certain teams, projects, or workspaces within the service.

    • Filters or Queries Too Restrictive

    Symptoms:
  • Queries return no results
  • Expected data is filtered out
    • Solutions:
  • Review Filter Criteria: Check any date ranges, status filters, or other criteria that might exclude the data you're looking for.
  • Test with Broader Filters: Remove filters one at a time to identify which one is excluding your data.
  • Check Default Filters: Some connectors have default filters (e.g., excluding archived items). Review the connector settings to see if defaults are affecting your results.
  • Verify Data Exists: Confirm the data you're looking for actually exists in the external service and meets your filter criteria when viewed there directly.

    • Getting More Help

    If you've tried the solutions above and are still experiencing issues:

  • Check Connector Documentation: Each connector has specific requirements and known limitations documented in the Zenmako docs.
  • Review Error Details: Error messages often contain specific codes or details that can help diagnose the issue.
  • Contact Support: If the issue persists, reach out to Zenmako support with:
    • - The connector you're using - The exact error message - Steps to reproduce the issue - When the issue started occurring