Troubleshooting: Leads & Clients — “Why can’t I…?”
Most blocked actions come down to two things working together: your role and your branch membership (plus, for some areas, whether the feature is turned on for your workspace). A button may be hidden or disabled in the interface, and the same rule is re-checked when you save — so an action can fail even if you got past the screen. Roles referenced below: Admin, Ops Manager, Sales Admin, Sales Member, Client Coordinator, Crew Leader. Crew Members have no access to leads or clients.A. Page access
A1. “Why can’t I see the Leads page at all?”
- Symptom: The Leads page shows “not found,” or a lead action returns “This feature is not available.”
- Cause: Two gates. (1) The Leads feature must be enabled for your workspace. (2) Your role must grant access to the Leads page.
- Who can (by role): Admin, Ops Manager, Sales Admin, Client Coordinator can open the Leads page. Sales Member and Crew Leader cannot.
- Resolution: Have the Leads feature enabled for your workspace, and use a role that grants Leads access.
A2. “Why can’t I see the Clients page at all?”
- Symptom: The Clients page (or a specific client page) shows “not found.”
- Cause: Mirrors A1, but for the Clients feature and Clients-page access.
- Who can (by role): Admin, Ops Manager, Sales Admin, Sales Member, Crew Leader, Client Coordinator can all open the Clients page.
- Resolution: Have the Clients feature enabled; use a role with Clients access.
A3. “Why does the lead/client page redirect me to login instead of showing ‘not found’?”
- Symptom: You’re sent to the login screen.
- Cause: You’re not signed in, or your session has no selected/assigned organization. This check runs before the feature and role checks.
- Resolution: Sign in, and make sure you have a selected/assigned organization.
B. Leads — create / edit / delete
B1. “Why can’t I create a new lead? (the ‘New Lead’ button is missing)”
- Symptom: No “New Lead” button on the Leads page.
- Cause: The button only appears for roles that can manage leads.
- Who can (by role): Admin, Ops Manager, Sales Admin, Client Coordinator. Sales Member and Crew Leader can’t create leads, so they see no button. (A Sales Member can view their own leads read-only — but can’t create, edit, or delete them; a Crew Leader has no lead access at all.)
- Resolution: Use a role that can manage leads.
B2. “Why does creating a lead fail server-side even though I clicked the button?”
- Symptom: An error toast appears after you submit the Create Lead form.
- Cause: Common reasons, in order:
- The Leads feature is off for your workspace → “This feature is not available.”
- Your session has no current branch → “A branch must be assigned before creating a lead.” Creating a lead requires you to have a current branch.
- Validation: last name and phone are required contact fields; the postal code must be exactly 5 digits (“ZIP code must be 5 digits”); a lead source, if provided, must be a valid selection.
- Role/organization: you must have a lead-management role and belong to the organization.
- Who can (by role): The same lead-management roles as B1, and you must have a current branch.
- Resolution: Make sure a branch is selected; fill in last name, phone, and a valid 5-digit ZIP.
B3. “Why can’t I edit a lead (status, branch, fields)?”
- Symptom: Inline edits or the Edit Lead form fail, or controls are disabled.
- Cause: Editing a lead requires a lead-management role, plus the same feature-enabled and organization checks as B2.
- Who can (by role): Admin, Ops Manager, Sales Admin, Client Coordinator. Sales Member and Crew Leader cannot.
- Resolution: Use a lead-management role.
B4. “Why can’t I change a lead’s branch?”
- Symptom: The branch selector is disabled with a tooltip, or the change is rejected.
- Cause (interface disabled): A Lead Activity is scheduled on the calendar → the selector is disabled with the tooltip: “This branch can’t be changed because a Lead Activity is scheduled on the calendar. Delete the event(s) to change the branch.” It is also disabled while a save is in progress.
- Cause (save rejected): When assigning a branch, you must be a member of the target branch. If not, the save is rejected with “You do not have access to this branch.”
- Side-effect: Changing the branch can automatically clear the assigned Client Coordinator if that coordinator can’t serve the new branch. (Client Coordinators are organization-wide; other assignees must belong to the branch.)
- Who can: Lead-management roles, and you can only assign branches you belong to.
- Resolution: Delete the scheduled Lead Activity first; pick a branch you’re a member of.
B5. “Why can’t I assign a particular Client Coordinator to a lead?”
- Symptom: Save fails with a validation message.
- Cause: The selected user must exist, belong to the organization, and hold the Client Coordinator role — otherwise the save is rejected with “clientCoordinator must be a client coordinator in this organization”. Also, the lead must already have a branch, or you’ll see: “A branch must be assigned to the lead before setting a client coordinator.”
- Resolution: Assign a branch to the lead first, then pick a user who has the Client Coordinator role and belongs to the organization.
B6. “Why can’t I assign a particular Sales Person / referrer to a lead?”
- Symptom: Save fails: “salesPerson must be a sales person in this organization” (or, for the referrer field, “salesPersonReferrer must be a sales person in this organization”).
- Cause: The selected user must hold the Sales Admin or Sales Member role (and exist and belong to the organization).
- Resolution: Choose a user with the Sales Admin or Sales Member role.
B7. “Why can’t I delete a lead? (no Delete option in the ⋯ menu)”
- Symptom: The “Delete Lead” menu item is missing, or delete fails.
- Cause: Deleting a lead requires a lead-management role, and if the lead has a branch you must be a member of that branch.
- Who can (by role): Admin, Ops Manager, Sales Admin, Client Coordinator — the same lead-management roles as B1. If the lead has a branch, you must also be a member of that branch.
- Side-effect: The lead is soft-deleted (it stops appearing in lists but isn’t permanently erased).
- Resolution: Use a lead-management role, and be a member of the lead’s branch.
B8. “Why is the ‘Schedule Lead Activity’ button disabled?”
- Symptom: The button is greyed out with the tooltip: “Please complete all required fields (First Name, Last Name, Address, and either Phone Number or Email) before scheduling a lead activity.”
- Cause: Scheduling requires all of: a primary contact with first name and last name and (phone or email), plus the lead’s address, city, state, and branch.
- Resolution: Fill in the contact name, an address (street/city/state), a phone or email, and assign a branch.
B9. “Why don’t my filter results / map pins show all leads?”
- Symptom: A lead exists but doesn’t appear in the list or on the map.
- Cause: Lead lists only show leads in your selected organization and exclude deleted leads. The “Unassigned” branch filter only matches leads with no branch. Map pins additionally require a geocoded address (latitude/longitude), so leads without one don’t appear, and the map shows a limited number of pins.
- Resolution: Confirm the lead isn’t deleted, is in the selected organization, and (for the map) has a geocoded address.
B10. “Why did saving a lead/contact fail with ‘Either email or phone number is required’?”
- Symptom: An error appears when saving a lead or contact.
- Cause: A contact must have at least one of email or phone (whitespace counts as empty). The phone number must also be a valid number, or you’ll see “Invalid phone number.”
- Resolution: Provide at least one of email or a valid phone number for each contact.
C. Clients — edit / delete / contacts
C1. “Why can’t I edit a client? (no pencil/edit button)”
- Symptom: The edit (pencil) button is missing on the client header, or the Edit Client form fails to save.
- Cause: Editing a client requires a role that can update clients, and an organization must be selected.
- Who can (by role): Admin, Ops Manager, Sales Admin, Sales Member, Crew Leader, Client Coordinator can all update a client.
- Resolution: Use any of the roles above and make sure an organization is selected.
C2. “Why can’t I delete a client? (no Delete in the ⋯ menu)”
- Symptom: The “Delete Client” item is missing, or delete fails.
- Cause: Deleting a client is restricted to management roles.
- Who can (by role): Admin, Ops Manager, Sales Admin can delete a client. Sales Member, Crew Leader, and Client Coordinator cannot. For certainty, use Admin or Ops Manager, as client deletion is restricted to management roles.
- Side-effect: The client is soft-deleted, and you’re returned to the Clients list.
- Resolution: Use Admin or Ops Manager.
C3. “Why can’t I remove a contact from a client / project?”
- Symptom: The remove-contact (trash) icon is hidden in the contact form, or saving returns “You do not have permission to remove contacts from this client/project.”
- Cause: Removing an already-saved contact requires permission to delete contacts. This is enforced both in the interface (the remove control is hidden) and on save, for both clients and projects.
- Who can (by role): Admin, Ops Manager, Sales Admin can remove existing contacts. Sales Member, Crew Leader, and Client Coordinator cannot remove existing contacts (they can still add and edit contacts).
- Resolution: Have an Admin, Ops Manager, or Sales Admin remove the contact. Other users can still add or edit contacts, just not remove existing ones.
C4. “Why does a client contact save fail validation?”
- Symptom: An error appears when saving client/project contacts.
- Cause: Same contact rule as B10 (email or phone required, valid phone number). Project contacts additionally require exactly one primary contact: “At least one contact must be set as primary.” / “Only one contact can be set as primary.” and “At least one contact is required.”
- Resolution: Set exactly one primary contact, and give each contact an email or phone.
C5. “Why can’t I see clients from another organization or branch in search?”
- Symptom: Client search returns nothing or “You do not have access to this organization.”
- Cause: Search is limited to organizations you belong to and branches you have access to. Search also requires at least 2 characters.
- Resolution: Search within your own organization and branch, and use at least 2 characters.
D. Projects
D1. “Why can’t I create a project? / convert a lead to a client-project?”
- Symptom: Project creation fails.
- Cause: Creating a project requires a role that can create projects, and the client must exist in your organization. When you create a project from the client page, you pick or add its primary contact right in the form.
- Who can (by role): Admin, Sales Admin, Sales Member, Client Coordinator can create projects. Ops Manager can view and update projects but cannot create them. Crew Leader cannot.
- Resolution: Use a role that can create projects (Admin, Sales Admin, Sales Member, or Client Coordinator). If New Project is missing from the client’s Create New menu, your role can’t create projects.
D2. “Why can’t I edit project details / contacts even though I can view the project?”
- Symptom: Edit buttons are hidden, or the update fails.
- Cause: Editing requires a role that can update projects, and you must be a member of the project’s branch.
- Who can (by role): Admin, Ops Manager, Sales Admin, Sales Member, Client Coordinator can update projects. Crew Leader cannot.
- Resolution: Use a role that can update projects, and be a member of the project’s branch.
D3. “Why can’t I edit the property address on a project?”
- Symptom: The address field is disabled with the tooltip: “This address is locked due to an existing estimate. Delete the associated estimate(s) to edit it.”
- Cause: When the project has an estimate, the address is locked.
- Resolution: Delete the associated estimate(s) to unlock the address.
D4. “Why can’t I load project proposals / media?”
- Symptom: Proposals or media fail to load with a permissions error.
- Cause: These project sections require you to belong to the project’s branch, and an organization must be selected.
- Resolution: Switch to (or be assigned) the project’s branch.
D5. “Why doesn’t the ‘View Project Summary’ link appear on a converted lead?”
- Symptom: The “converted into a client” banner shows, but there’s no link.
- Cause: The link only appears if you’re a member of the lead’s branch. Without branch access you see the banner text but not the link.
- Resolution: Get access to the lead/project’s branch.
E. Cross-cutting organization / branch scoping
E1. “Why do reads return nothing for a record I know exists (no error)?”
- Symptom: A lead, client, or project silently shows “not found” or is absent.
- Cause: Records are scoped to your selected organization (or, if none is selected, the organizations you belong to). Leads are further limited to those with no branch or a branch you belong to — so a lead assigned to a branch you’re not in is invisible to you.
- Resolution: Select the correct organization, and make sure you have membership in the relevant branch.
E2. “Why does a server action say ‘You do not have access to this organization’?”
- Symptom: A lead, client, or project action is blocked with that message.
- Cause: The action resolves a target organization (your selected one, or your only one) and requires you to belong to it. Missing context gives “Invalid request: Missing organization context.”
- Resolution: Select an organization you belong to before retrying.
E3. “Why can an API / service-account token act on leads/clients but a regular user can’t (or vice-versa)?”
- Cause: Automated access comes in two forms, and they’re bounded differently. An app connected on your behalf can only do what you granted it and what your own role already allows — the two are combined, so the app is denied anything your role can’t do, even where you granted the permission. A service-account API key is tied to the whole workspace rather than to a person, so its access is exactly the permissions granted to the key, with no personal role narrowing it further — which is why a key can act on a lead in any branch of its workspace, while a regular user is limited to the branches they belong to. Either way, a token missing the leads or clients permission is denied, and a feature turned off for the workspace blocks the token too.
- Branch: A service-account key has no active branch to fall back on, so when it creates a lead it must name the branch to file it under; it can name any branch in its own workspace, and a branch outside that workspace comes back “not found.” (An app connected on your behalf must likewise name the branch when creating a lead.)
- Resolution: Grant the token the leads/clients read or write permission it needs, confirm the feature is enabled, and — when a service-account key or connected app creates a lead — include the branch to file it under.
Quick role → capability matrix (Leads & Clients core actions)
Note: lead deletion is available to all four lead-management roles (Admin, Ops Manager, Sales Admin, Client Coordinator), subject to branch membership. Client deletion is narrower: Admin, Ops Manager, and Sales Admin only.