Troubleshooting / Error Guide

IF you’re trying to manage tenants/users/org settings (MSP/admin tasks)
​THEN you should be using admin.hatz.ai (admin portal).
​

IF you’re an end user chatting/using tools in your org (NOT an MSP)
​THEN you should be using your org’s subdomain (your unique Hatz URL), not admin.hatz.ai.
Source: “Access Restricted” note in the error guide + login troubleshooting context.

IF the app won’t load (chat history/workflows not loading) and your internet is fine
​THEN whitelist Hatz domains on your network/security stack:

Source:

IF you see “Access Restricted”
​THEN confirm you’re logging into the correct place:

Source:

Start by identifying the user type:

IF an ACTIVE Admin user needs a password reset
​THEN in admin.hatz.ai go to Settings → Users and Roles → (…) → Reset Password.

IF an INACTIVE Admin user didn’t get the invite / invite expired
​THEN in admin.hatz.ai go to Settings → Users and Roles → (…) → Resend Invite.

IF an ACTIVE Customer user needs help logging in
​THEN in admin.hatz.ai go to Tenants → select tenant → (…) → Resend Invite (sends reset/setup instructions).

IF a PENDING Customer user didn’t receive the invite / it expired
​THEN in admin.hatz.ai go to Tenants → select tenant → (…) and choose either:

Source (all of the above):

IF chat is taking too long to respond
​THEN

Source:

(Helpful context on model selection UI/attributes:)

IF an old/long-running chat stops giving good outputs
​THEN assume you’re hitting the model’s context window limits; move to a fresh chat (or reduce what you’re asking it to consider).

Source (context window note):

IF you’re using an OpenAI model in Hatz but results differ from ChatGPT on openai.com
​THEN check these common causes:

Source:

IF a file won’t upload even though it’s under 30MB
​THEN it may still exceed the token limit for the specific LLM you selected; try a different model (or reduce the document size/scope).

IF a file won’t upload even though it’s under 30MB
​THEN it might not be an accepted file type. We can evaluate these issues on a case by case basis.

Source:

IF web search or an integration isn’t doing what you expect
​THEN

Sources:

IF users can’t find a model they expected (or you want to standardize model choice)
​THEN check org-level settings:

Source:

IF the issue is “credits, quotas, or usage limits”
​THEN use the official credit usage FAQ (most accurate source, updated policy):

(Background explainer in docs collection:)

IF you need multiple steps / multi-output / run history
​THEN build a Workflow.
​

IF you need a reusable chatbot persona that can use tools/integrations and sources every time
​THEN build an Agent (also usable directly in Chat).
​

IF you need a single AI “app” (prompt + inputs), including API usage
​THEN build an App.
Source: https://docs.hatz.ai/en/articles/12281902-workshop-faq

IF you can’t insert a prior step output into a later step
​THEN confirm the steps are connected (connections are required to insert earlier outputs into later steps).
Source: https://docs.hatz.ai/en/articles/11328145-workflows-beta

IF Step 2 runs but behaves like it didn’t get Step 1 context
​THEN explicitly insert Step 1’s Output into Step 2’s prompt (treat each step like a distinct automation and include the needed context).
Source: https://docs.hatz.ai/en/articles/11328145-workflows-beta

IF you expected the workflow’s Web Scraper Step to click links / crawl the domain
​THEN note it only scrapes the single page URL you provide (it does not crawl the whole site).
​THEN either (a) provide the exact URL you need, or (b) redesign steps so earlier outputs produce the right URL for the scraper step to use.
Source: https://docs.hatz.ai/en/articles/11328145-workflows-beta

IF you need to debug cost, latency, or model choice inside a workflow
​THEN use Workflow Run History to inspect:

IF you want to share outputs as documents
​THEN export any workflow step to PDF or Word.
​

IF you want branded/structured Word docs
​THEN use a Document Processing Step with a .docx template and map placeholders (e.g., {{client_name}}) to workflow data.
​

IF you need to fill an existing PDF form
​THEN upload a fillable PDF and map workflow values to its form fields.
Source: https://docs.hatz.ai/en/articles/12332454-ai-document-processing-steps-and-exports-in-workflows

IF you can’t find where to build/manage workflows
​THEN go to the Workshop and look under Automations (Workflows are inside Workshop).
Source: https://docs.hatz.ai/en/articles/11328145-workflows-beta
(Workshop navigation/context): https://docs.hatz.ai/en/articles/12572765-the-hatz-workshop

IF an agent can’t use tools/integrations
​THEN verify both:

IF you hit a limit adding tools
​THEN note agents can select up to three tools.
​THEN either swap tools, or create multiple specialized agents and switch agents when needed.
Source: https://docs.hatz.ai/en/articles/12602274-agents

IF the agent’s behavior is inconsistent
​THEN tighten the System Prompt (Instructions): define role, context, tasks, constraints, and output format (so it runs every time).
Source: https://docs.hatz.ai/en/articles/12602274-agents

IF others can’t access your agent
​THEN check sharing settings—agents default to Private; enable Share with Organization to make it available org-wide.
Source: https://docs.hatz.ai/en/articles/12602274-agents

IF you created an agent but can’t figure out how to talk to it in Chat
​THEN use the agent selector in Chat (robot icon) and select your agent from the list.
Source: https://docs.hatz.ai/en/articles/12602274-agents

IF integrations aren’t appearing or you can’t connect them
​THEN check where you’re trying to connect from:

IF you need beta integration access and don’t see the integration
​THEN enable beta features for the right place:

IF results are stale or it didn’t search/scrape when it should have
​THEN either:

IF you’re debugging a workflow/agent/integration and want proof of what happened
​THEN use Inline Tool Calling to view:

IF you duplicated a community template but can’t find it / edit it
​THEN check My Items in Workshop (duplicating creates your editable copy; items start private).
Source: https://docs.hatz.ai/en/articles/12572765-the-hatz-workshop

IF you published something but the wrong people have access
​THEN re-check publishing/sharing scope (private vs org vs client tenants).
Source (apps publishing, relevant pattern for access scoping): https://docs.hatz.ai/en/articles/10716519-publishing-apps

IF you’ve followed the branch above and it still fails
​THEN contact Hatz support: [email protected] (listed in Hatz docs).
Source: