AccessControlUnauthorizedAccount is a custom error from OpenZeppelin Contracts v5. It means the address that called a function does not hold the role that function requires, so the contract refused the call. The error carries two values: the account that was rejected and the neededRole it was missing. To fix it, have an address that holds that role’s admin role call grantRole(neededRole, account), or send the transaction from an address that already has the role.
Below we explain how to read the error, the five situations that cause it (all reproduced in Foundry tests and on a local fork of Core mainnet), and how to fix each one.
What AccessControlUnauthorizedAccount Means
OpenZeppelin’s AccessControl module gives a contract role-based permissions. Each role is a bytes32 ID, usually written as keccak256("MINTER_ROLE"). Functions protected by the onlyRole(ROLE) modifier call _checkRole. In the v5.6.1 source (the latest release on npm when we checked on 20 Nov 2026), that check is:
function _checkRole(bytes32 role, address account) internal view virtual {
if (!hasRole(role, account)) {
revert AccessControlUnauthorizedAccount(account, role);
}
}
The error itself is defined in IAccessControl.sol:
error AccessControlUnauthorizedAccount(address account, bytes32 neededRole);
Its 4-byte selector is 0xe2517d3f, which we confirmed with cast sig "AccessControlUnauthorizedAccount(address,bytes32)". If a wallet or explorer shows raw revert data starting with 0xe2517d3f, this is the error.
The v4 version of the same error
In OpenZeppelin v4.x, the same check reverted with a text string instead: AccessControl: account 0x… is missing role 0x… (see the v4.9.6 source). The v5.0.0 changelog replaced revert strings with custom errors and calls out AccessControl as an example. So if your off-chain code matches the old string with a regex, it will miss v5 contracts.
How to Decode the Error Data
When we called a role-protected mint function from an address without the role on an Anvil fork of Core mainnet (chain ID 1116), the RPC returned:
execution reverted: custom error 0xe2517d3f:
data: "0xe2517d3f
000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266
9f2df0fed2c77648de5860a4cc508cd0818c85b8b8a1ab4ceeef8d981c8956a6"
(Line breaks added.) After the selector come two 32-byte words: the rejected address, then the missing role. You can decode it with Foundry:
cast decode-error 0xe2517d3f…956a6 --sig "AccessControlUnauthorizedAccount(address,bytes32)"
To work out which role a hash stands for, hash the likely names and compare. 0x00…00 is always DEFAULT_ADMIN_ROLE. Common role hashes we computed with cast keccak:

| Role name | bytes32 value (keccak256 of the name) |
|---|---|
| DEFAULT_ADMIN_ROLE | 0x0000…0000 (all zeros, not a hash) |
| MINTER_ROLE | 0x9f2df0fe…8956a6 |
| PAUSER_ROLE | 0x65d7a28e…0d862a |
| UPGRADER_ROLE | 0x189ab7a9…c9d2e3 |
These only match if the contract used those exact strings. If none match, read the verified source on the block explorer, or call the contract’s public role constant (for example MINTER_ROLE()) directly. Our guide to Foundry cast commands on Core covers the read-only calls you need.
What Causes It: 5 Cases We Tested
We wrote a small ERC-20 with MINTER_ROLE and PAUSER_ROLE on OpenZeppelin 5.6.1 and ran nine Foundry tests, all passing. Here are the causes that came out of them.
1. The caller simply does not have the role
The most common case. A random address calling mint reverted with AccessControlUnauthorizedAccount(caller, MINTER_ROLE). If you are a normal user of a dapp, this usually means you called an admin-only function. That is the permission check doing its job, not a bug you can fix from your side.
2. The deployer has the admin role but not the working role
This catches a lot of developers. Granting DEFAULT_ADMIN_ROLE in the constructor does not give that address MINTER_ROLE. In our test, the admin calling mint got the same error. The admin can grant roles, but it still has to grant one to itself before it can use it.
3. A non-admin tried to grant or revoke a role
grantRole and revokeRole are themselves protected by onlyRole(getRoleAdmin(role)). When a non-admin called grantRole(MINTER_ROLE, …), the error showed neededRole = 0x00…00. In other words, the missing role was the admin role, not the minter role.
4. The call went through another contract
The check uses _msgSender(), which is normally msg.sender, the address that called the contract directly. We granted MINTER_ROLE to a wallet, then had that wallet call a helper contract that called mint. It reverted, and the account in the error was the helper contract, not the wallet. Routers, multisigs, scripts that use a proxy, and other contracts all hit this. The fix is to grant the role to the contract that makes the call.
5. A custom role admin, or the admin role was renounced
Contracts can change who manages a role with _setRoleAdmin. After we made MINTER_ROLE the admin of PAUSER_ROLE, the default admin’s grantRole(PAUSER_ROLE, …) failed and the error asked for MINTER_ROLE. In a separate test, the only admin called renounceRole(DEFAULT_ADMIN_ROLE, …). After that, every grantRole failed with neededRole = 0x00…00. If no other address holds the admin role, that role can no longer be granted through grantRole.
How to Fix AccessControlUnauthorizedAccount
If you are a user
- Check that you are on the right app and calling the function you meant to. Role-gated functions such as minting, pausing or upgrading are meant for the project’s operators.
- If a project told you that you were given a role (for example a whitelist minter), compare the
accountin the error with the wallet you are connected with. The wrong account selected in your wallet is a frequent cause. - Don’t approve “fix” transactions from strangers who offer to “unlock” a role for you. Only an existing role admin can grant roles.
If you are a developer
- Decode the error. Get the
accountandneededRole, as shown above. - Check the role.
cast call <contract> "hasRole(bytes32,address)(bool)" <role> <account>should returnfalse. - Find the role’s admin.
cast call <contract> "getRoleAdmin(bytes32)(bytes32)" <role>. By default this returns0x00…00(DEFAULT_ADMIN_ROLE). - Grant the role from an admin. From an address holding that admin role, call
grantRole(role, account). On our Core fork, the admin granted itselfMINTER_ROLE,hasRolethen returnedtrue, and the samemintcall succeeded. - Grant to the right address. If a contract, multisig or relayer makes the call, the role must go to that address (see case 4).
- Fix the deployment script. Grant working roles in the constructor or deploy script, not just
DEFAULT_ADMIN_ROLE. Test it in a fork before you go live. Our guide to forking Core mainnet with Anvil shows the setup we used.
If the admin role has been renounced and no address holds it, grantRole cannot fix things. Unless the contract has another upgrade or recovery path, you will need to redeploy. OpenZeppelin’s API docs recommend AccessControlDefaultAdminRules for extra protection around the default admin role.
Related Errors You Might See
- AccessControlBadConfirmation: thrown by
renounceRolewhen thecallerConfirmationaddress is not the caller. We confirmed this in our tests. It is a separate error, and the OpenZeppelin source notes not to confuse the two. - OwnableUnauthorizedAccount: the single-owner version used by
Ownablecontracts. See our OwnableUnauthorizedAccount guide. - Generic “execution reverted”: what some wallets show when they can’t decode custom errors. Our execution reverted explainer covers how to get the underlying reason.
FAQ
Does the admin automatically have every role?
No. DEFAULT_ADMIN_ROLE can grant and revoke roles (by default), but hasRole(MINTER_ROLE, admin) stays false until the admin is granted MINTER_ROLE.
Why does the error show a contract address instead of my wallet?
Because the check uses the direct caller. If your transaction passes through another contract, that contract is the caller, so it needs the role.
Can I see this error before paying gas?
Usually, yes. On our fork the revert appeared during gas estimation, before anything was broadcast. Wallets typically warn you that the transaction is likely to fail.
Is this specific to Core?
No. It is OpenZeppelin Solidity code, so it behaves the same on any EVM chain. We tested on a Core mainnet fork because Core is EVM-compatible.
How We Tested
On 20 November 2026 we used Foundry 1.9.0 and OpenZeppelin Contracts 5.6.1. We ran nine local unit tests, then deployed the same contract to an Anvil fork of https://rpc.coredao.org (chain ID 1116) and used cast to trigger the error, decode it and fix it. No real mainnet transactions were sent.
This article is for educational purposes only and is not financial or investment advice. Always review smart contract permissions carefully, and test on a fork or testnet before making changes on mainnet.
