Stellar: Error "xlm.account.not.found"

When interacting with the Stellar blockchain to fetch an address balance, you may encounter the following error:

{
    "statusCode": 404,
    "errorCode": "xlm.account.not.found",
    "message": "Account #####  not found on mainnet. Probably there were no assets sent there before.",
    "cause": "Title: Resource Missing. Type:  Detail: The resource at the url requested was not found.  This usually occurs for one of two reasons:  The url requested is not valid, or no data in our database could be found with the parameters provided.."
}

This error indicates that the specified Stellar account does not exist on the Stellar network. Stellar accounts are only created when they receive their first funding. Without this initial funding, the account is not recorded on the Stellar ledger.

Resolving the Error

1. Fund the Account
   • To create a Stellar account, send at least 1 XLM to the address. This is the minimum required to activate the account with no subentries.
   • Use a Stellar wallet or any service supporting XLM transactions to perform this transfer.
2. Verify the Address
   • Ensure the address provided is correct and follows the Stellar account address format.
   • Double-check that the network (mainnet or testnet) matches your intended operation.
3. Check the Funding Amount
   • If the account is expected to have subentries, ensure you send enough XLM to cover the additional minimum balance requirements.

📘

Info

For more details, refer to Stellar's official documentation on minimum balance requirements.