Troubleshooting

Errors from setup, commissions, approvals, and invoice payment, with causes and fixes.

The API masks most custom errors as "Unexpected error." Check the server log for the real message. The dashboard shows the message for the cases below.

Sign-in and setup

ProblemCause and fix
Redirects to /dashboard/initNo users yet. Create the first admin
Redirects to /dashboard/no-accessThe role lacks canAccessDashboard
Dashboard shows an empty error pageCheck the server log. A wrong DATABASE_URL or unapplied migration is the usual cause
npm run dev failed to startAnother Next.js process holds the lock for this folder. Stop it, then retry
Sidebar setup card is missingThe agency already has an athlete, onboarding is done or dismissed, or the role lacks canManageOnboarding
Setup fails partwayRun it again. Saved records are reused
Setup money phase is slowIt runs many commands one after another. A remote database makes it slower

Commissions

MessageCause and fix
Idempotency key requiredSend an idempotencyKey
Idempotency key was already used with a different requestUse a new key for different arguments
Command already processingThe same key is in flight. Retry shortly
Athlete not foundThe athlete does not exist or you are not their lead agent or support staff
Unique scheduled payments requiredThe list is empty or has duplicates
Received uninvoiced payments in one currency requiredA payment is not received, is already on an invoice, or the currencies differ
Valid payment amount and reference requiredThe amount is zero, above the balance, or the reference is empty
Invalid state transitionThe record is not in a status that allows the change
Record changed concurrentlyAnother request changed it first. Reload and retry
Entry cannot be reversed twiceReversals are exact and happen once
Void the invoice before reversing its accrualThe payment is on an invoice
Reverse payments before voiding a paid invoiceAn invoice with payments cannot be voided

Contracts and agreements

MessageCause and fix
Playing commission exceeds union capLower playingCommissionBps or raise capBps
Active representation agreement already existsAnother signed, filed, or active agreement covers the same scope
Active playing representation requiredThe contract needs a linked, in-date playing or both agreement that is signed, filed, or active
Union commission cap exceededThe agreement's playing rate is above its cap
Signed source requiredSchedules can be generated only for a signed or active contract or deal

Recruiting and endorsements

MessageCause and fix
Contact window has not openedcontactAllowedFrom is in the future
Invalid recruiting stageUnknown stage, or the athlete is already there
Exclusivity conflict with an active dealAnother signed or active deal has the same category and an overlapping term. Request an override
HTTPS proof requiredSend a proof link that starts with https://

Approvals

MessageCause and fix
The requester cannot decide their own approvalA different user with canApproveActions must decide
Approval is already approved, rejected, or consumedA request is decided once
Approval has expiredRequests last one hour. File a new one
Approval does not match this requestThe target, reason, or amount differs from the request
Approval must come from a different userThe approver and the requester are the same person
Approval was already used or has expiredAn approval is single use
Only an unpaid sent invoice can be written offThe invoice is not sent or partially_paid, or has no balance

Trust

MessageCause and fix
Insufficient client trust balanceThe entry would take the balance below zero
Sent athlete invoice requiredA commission transfer needs a sent or partially_paid invoice for the same athlete
Transfer exceeds invoiceTransfers against the invoice would pass its total
Invalid trust entryWrong entry type, a zero or fractional amount, or no reference

Invoice payment

MessageCause and fix
No invoice matches those detailsThe email or invoice number is wrong, or the invoice is a draft or void
Invoice not foundThe proof is missing, expired, forged, or for another invoice
Card payments are not configuredNo installed provider with code pp_stripe_stripe
Invoice is not payableThe invoice is not sent or partially_paid, or has no balance
Invoice changed; reload and retryThe balance changed while the payment was being reserved
Provider amount differs from the invoice paymentStripe reports a different amount. The payment needs review
Payment stuck as unknownStripe captured the money but the invoice could not take it. Review and fix by hand
Card form does not appearNEXT_PUBLIC_STRIPE_KEY is missing or not a publishable key

On this page