Troubleshooting

Find the message you see, then follow its fix. Messages are quoted as TrueUpp shows them; parts that change, such as names and numbers, are in angle brackets. If your message isn't here, or the fix doesn't work, email hello@trueupp.com with the message and the time you saw it.

Connecting Stripe

"That is a secret key. Create a restricted key…"

Cause: you pasted a key starting with sk_. TrueUpp refuses secret keys because they can do far more than it needs.

Fix: create a restricted key with only the listed permissions. See create a restricted key.

"Paste a Stripe restricted key; it starts with rk_test_ or rk_live_."

Cause: what you pasted isn't a restricted key, or it was cut short.

Fix: copy the whole key from Stripe again. It starts with rk_test_ or rk_live_.

"Stripe rejected that key."

Cause: Stripe didn't accept the key. It was copied incompletely, or it has been revoked.

Fix: copy it again, or create a new restricted key.

"The key is missing these permissions: …"

Cause: TrueUpp checks each permission it needs before saving the key. The message names the ones that are missing.

Fix: edit the key in Stripe, set the permissions named in the message, and paste it again. See create a restricted key.

"The webhook signing secret starts with whsec_."

Cause: what you pasted as the signing secret isn't one. The endpoint URL and the secret are easy to mix up.

Fix: in Stripe, reveal the webhook's signing secret and paste that. See add the webhook endpoint.

Mapping customers

"Stripe: No such customer: … TrueUpp is connected to …"

Cause: the cus_ ID you searched for lives in a different Stripe account, sandbox or mode from the connected key. The message names the account and mode TrueUpp is connected to.

Fix: create the key in the account that holds the customer and reconnect. See pick the right Stripe account and Stripe troubleshooting.

"A Stripe customer id starts with cus_."

Cause: you pasted another kind of ID. Newer Stripe accounts show an account ID starting with acct_ on the customer page, which is a different object.

Fix: paste the ID that starts with cus_, or search by name or email. See map each contract.

"A NetSuite customer internal id is a number."

Fix: enter the customer's internal ID from NetSuite, digits only. See connect NetSuite.

Approving lines

"Resolve the open <Review or Data> exception first (<code>): …"

Cause: the line has an open exception that blocks approval. The message names its code.

Fix: click Resolve exception on the line, resolve it with a note, then approve. Look up the code in the exception reference.

"<N> selected line(s) have open Review or Data exceptions; bulk approve only takes clean lines."

Fix: resolve those exceptions first, or approve the clean lines and deal with the others one by one. See approving clean drafts.

"Some lines changed since you loaded the page (a newer run replaced them). Reload and try again."

Cause: someone ran the close again while you had the page open, and a line you selected now has a newer version.

Fix: reload the page, check the new version, and decide again. See line versions.

"<N> line(s) can't be <approved> from their current status (…)."

Cause: the line's status doesn't allow that decision. Only drafts can be approved or held. Approved, pushed and invoiced lines are locked.

Fix: to change a locked period, let a later run post an adjustment. See locked periods.

"Give a reason for rejecting."

Fix: write a note saying why, then click Reject.

Pushing to Stripe or NetSuite

"<N> skipped (no Stripe customer mapped)."

Cause: the contract has no Stripe customer. Nothing was sent for its lines. NetSuite shows "no NetSuite customer mapped" for the same reason.

Fix: map the contract to a customer, then push again. See map each contract and the customer_unmapped exception.

"skipped (zero amount: nothing to bill)"

Cause: the approved line is $0. TrueUpp doesn't send empty items.

Fix: none needed.

"Push to Stripe failed: … permission …"

Cause: Stripe refused the request because the restricted key lacks a permission, such as invoice write. The message quotes Stripe's error, which names the permission.

Fix: edit the restricted key in Stripe, set the permission named in the message, then push again. See Stripe troubleshooting and push_failed.

"Push to Stripe failed: …" or "Push to NetSuite failed: …"

Cause: the billing system returned an error. The line stays approved, and the message quotes the error.

Fix: act on the error, then push again. A successful push closes the exception. See push_failed.

"Four-eyes is on: someone other than the approver has to push these lines."

Cause: your workspace requires the person who pushes to be different from the person who approved, and you approved at least one of these lines.

Fix: ask another approver or admin to push. See four-eyes approval.

"Connect Stripe in Settings before pushing."

Fix: an admin connects Stripe in Settings › Connections. See connecting Stripe. For NetSuite the message is "Connect NetSuite in Settings before pushing"; see NetSuite.

Lines stay "Pushed" after you finalize the invoice

Cause: the Stripe webhook isn't reaching TrueUpp, so it never hears that the invoice was finalized.

Fix: check the endpoint URL, the five events and the signing secret. Settings › Connections and the Metrics page show when the last webhook arrived. See add the webhook endpoint.

"Invoice <id> was voided in Stripe. The line stays as history. Re-push it or write it off."

Cause: someone voided or deleted the draft invoice or item in Stripe.

Fix: in Exceptions, choose Resolve and re-push, or resolve with a note to write it off. See invoice_voided_externally.

Access and plans

"Your role (<role>) can't do that."

Cause: your role doesn't include that action. Analysts can't approve, push or resolve exceptions. Only admins can change connections, settings, the team and billing. The run page may also say "Your role can't approve lines" or "Your role can't push".

Fix: ask an admin to do it, or to change your role. See team and roles.

"This workspace is read-only until the subscription is settled. Exports still work."

Cause: a payment has been overdue for more than 14 days, or the subscription has ended.

Fix: an admin settles payment in Settings › Billing. Meanwhile you can still read and export everything. See overdue payments.

"This needs the <Growth or Scale> plan. Upgrade in Settings › Billing."

Fix: an admin changes plan in Settings › Billing. See changing plans.

"<Plan> includes <N> active contracts and you have <N>."

Cause: adding or restoring this contract would go over your plan's limit of active contracts.

Fix: archive a contract you no longer bill, or move up a plan. See changing plans.

"This invitation has expired or was already used."

Cause: invitations last 7 days and work once.

Fix: ask an admin to invite you again. If the message says the invitation is for another address, sign in with that address. See team and roles.

Close runs

"This run produced no lines in its scope."

Cause: no contract has a period that ends inside the run's dates, or the contracts' terms don't cover those periods.

Fix: check the run's Close periods ending by date and the contracts' start and end dates. See start a run by hand.

Usage you just imported isn't in the run

Cause: it was imported after the run's usage cutoff. The run shows an imported_after_cutoff exception.

Fix: rerun. See the usage cutoff.

"This run failed: …"

Fix: act on the error shown and start a new run. If you can't tell what it means, email hello@trueupp.com.

"No billing line for that period yet. Run a close that covers it first."

Cause: you asked for a statement for a period that no run has closed.

Fix: run a close that covers the period, then generate the statement. See audit statements.

Imports and contracts

"Missing column(s): …"

Cause: the CSV's header row doesn't have the columns TrueUpp expects. The message lists the missing and expected columns. Nothing was imported.

Fix: fix the header and upload again. See usage CSV formats.

"A contract for account <id> already exists."

Fix: each account ID can have one contract. To change its terms from a date, amend it instead. See amendments.

"This contract has lines in Stripe, so it can only be archived, not deleted."

Cause: lines from this contract were pushed to your billing system, so its history has to stay.

Fix: archive it. See deleting a contract.

Usage webhook returns 401, 422 or 429

Cause: 401 means the token is missing or revoked. 422 means at least one row is invalid, and nothing was imported. 429 means more than 120 requests in a minute.

Fix: see the usage webhook API.

Anything else

"Something went wrong on our side. Nothing was changed."

Cause: an error TrueUpp didn't expect.

Fix: try again. If it happens again, email hello@trueupp.com with what you were doing and the time.