Skip to main content

Troubleshooting

Troubleshooting​

Common Issues and Solutions​

App Installation Fails​

  • Check manifest.json: Ensure assets/manifest.json exists and contains valid JSON
  • Verify manifest fields: Must include app.name, app.version, and app.description
  • Check ZIP structure: Main file must be named {app_name}.lua
  • Verify version format: Use semantic versioning in manifest (e.g., 1.0.0, 2.1.3-beta)
  • Remove test files: Don't include spec/, turn.lua, or .rockspec files

Common error messages:

  • :manifest_not_found - Missing assets/manifest.json file
  • :invalid_manifest_json - Malformed JSON in manifest file
  • :invalid_manifest_format - Missing required fields in manifest

Contact Subscriptions Not Working​

  • Ensure set_contact_subscriptions() is called in the install event
  • Verify field names match exactly (case-sensitive)
  • Check the return value for error messages: 
    local success, reason = turn.app.set_contact_subscriptions(fields)
    if not success then
        turn.logger.error("Subscription failed: " .. reason)
    end

Journey Events Not Triggering​

  • Verify the function name matches between Journey and app
  • Check return format: must be "continue" or "wait", or "error"
  • For async flows, store and use chat_uuid correctly: 
    -- Store chat_uuid when initiating async operation
    store_webhook_data(webhook_id, data.chat_uuid)

    -- Later, in webhook handler
    local chat_uuid = retrieve_webhook_data(webhook_id)
    turn.leases.send_input(chat_uuid, result)

HTTP Requests Failing​

  • Check URL format and ensure it's complete (including https://)
  • Verify headers are properly formatted: 
    local body, status = turn.http.request({
        url = "https://api.example.com/endpoint",
        method = "POST",
        headers = {
            ["Content-Type"] = "application/json",
            ["Authorization"] = "Bearer " .. token
        },
        body = turn.json.encode(data)
    })

Module Loading Issues​

  • Ensure module paths are relative to ZIP root
  • Use forward slashes in require statements: 
    local utils = require("my_app.utils")  -- Correct
    -- NOT: require("my_app\\utils")       -- Wrong
    -- -- NOT: require("my_app/utils")     -- Wrong

Debugging Tips​

  1. Use Logging Extensively:

    turn.logger.debug("Starting process with data: " .. turn.json.encode(data))
    turn.logger.info("Process completed successfully")
    turn.logger.error("Failed to process: " .. error_message)

  2. Check App Logs: View logs in Turn UI → Settings → Apps → Your App → Logs

  3. Test Locally First: Use the mock turn.lua API for unit testing

  4. Handle Nil Values: Always check for nil before using values:

    local value = data and data.field or "default"

  5. Validate Event Data: Different events have different data structures:

    if event == "journey_event" then
        if not data.function_name then
            turn.logger.error("Missing function_name in journey_event")
            return "error", "Invalid journey event data"
        end
    end

Getting Help​

If you're still experiencing issues:

  1. Check the app logs for detailed error messages
  2. Review the example apps for working patterns
  3. Contact Turn.io support with:
    • Your app's UUID
    • The specific error messages
    • Steps to reproduce the issue