# Mintlab agent troubleshooting

Entry: https://mintlab.website/llms.txt
Playbook: https://mintlab.website/agents/playbook.txt

------------------------------------------------------------------------------
Auth / principal
------------------------------------------------------------------------------

Symptom: "You must be authenticated" / anonymous rejected
- Ensure derivation_origin is https://mintlab.website (not nns.ic0.app alone).
- Re-resolve app principal for Mintlab before updates.

Symptom: Wrong account funded
- getAgentMintReadiness().accountIdHex is authoritative.
- Memory/workflow account IDs are often for a different principal — ignore if mismatch.

------------------------------------------------------------------------------
ICP funding
------------------------------------------------------------------------------

Symptom: getUserICPBalance is 0 after transfer
- You may have transferred to the wrong Account ID or to the principal’s default
  account instead of Mintlab’s in-app subaccount hex.
- Confirm with account_balance_dfx on the exact readiness hex.

Symptom: Insufficient ICP on mint
- Need mainMintPriceE8s + fee buffer (see enoughIcpForOneMint).
- getMintConfig for current mainMintPriceE8s.

------------------------------------------------------------------------------
Images / mint
------------------------------------------------------------------------------

Symptom: "Invalid JPEG marker" / metadata chunks not allowed
- Strip EXIF/XMP; save clean JFIF JPEG or PNG.
- PIL: convert RGB, quality=85, no exif=True if available.

Symptom: Image too large
- maxUploadImageBytes = 130000 raw. Compress before upload.
- No server recompression.

Symptom: MCP hangs building huge data URL candid
- Stop. Use uploadMintImageBase64 or chunked Base64 (16KB chunks).
- Never paste multi-MB PNG Base64 into one candid string if the tool times out.

Symptom: "Uploaded mint image expired"
- Pending uploads last 2 hours. Re-upload then mint promptly.

Symptom: "pending mint images" limit
- Max 2 per principal. Mint or wait for TTL; cancel unused chunk sessions.

Symptom: Unfinished paid mint blocks new mint
- getMyPendingMintPayments → retryPendingMintPayment or dismiss.

Symptom: moderation rejection
- getModerationConfig; avoid copyrighted logos/characters when moderation enabled.

------------------------------------------------------------------------------
Transfer
------------------------------------------------------------------------------

Symptom: sendNFT fails with ownership error
- Use wallet nftId from mint receipt (nfts[i].id), not collection token index alone
  if they differ in your mental model — receipt id is correct for sendNFT.
- Recipient must be a Principal, not Account ID hex.

Symptom: Registered external NFT cannot send from app
- Must vault/deposit first (see playbook / human Wallet receive flows).

------------------------------------------------------------------------------
Marketplace
------------------------------------------------------------------------------

Symptom: buyFixedListing fails insufficient funds
- Same in-app balance as mint; fund accountIdHex.

Symptom: Concurrent ICP operation lock
- "Another ICP operation is already using this account balance" → wait and retry once.

------------------------------------------------------------------------------
Tooling / sessions
------------------------------------------------------------------------------

Symptom: Long interruption during shell image prep
- Compress offline first; then only short canister calls.
- Prefer mintUserNFTAndSend to reduce steps.

Symptom: Candid decode errors
- Check method signatures via canister interface / getAgentCapabilityGuide keyMethods.
- Opt null vs missing fields; principal vs text mistakes.

------------------------------------------------------------------------------
Where to get live help from the canister
------------------------------------------------------------------------------

getAgentCapabilityGuide()     — steps, pitfalls, documentationUrls
getAgentMintReadiness()       — personalized next steps
getMintConfig()               — prices / enabled flags
getModerationConfig()         — moderation user message