Neo Smart ChainJoin the launch

Developer documentation

Troubleshooting

Common errors when developing and deploying on Neo Smart Chain, and how to fix them.

Version
0.1
Last updated
November 17, 2026
Status
Draft
Download PDF

1.Connection and wallet

SymptomLikely causeFix
Wallet says the chain ID does not matchThe RPC URL belongs to a different network than the chain ID you enteredUse the values from the network table and check eth_chainId
Wallet cannot add the networkMissing or malformed fields in wallet_addEthereumChainProvide a hex chain ID, an HTTPS RPC URL and a currency with 18 decimals
Requests time out or return 429You hit the public rate limitSlow down, cache responses or use a dedicated endpoint
Transaction shows as pending foreverThe fee is too low or an earlier nonce is stuckResend with higher fees or replace the pending transaction with the same nonce

2.Deployment

ErrorLikely causeFix
insufficient funds for gasThe deployer has too little native currencyFund the account from the faucet on testnet
nonce too lowA transaction with this nonce was already minedRefresh the nonce, or reset your wallet account activity
invalid opcode or deployment reverts with no reasonBytecode compiled for a newer EVM version than the network supportsLower evm_version in your compiler settings and redeploy
max code size exceededThe contract is larger than the size limitEnable the optimizer, split into libraries or contracts, or remove unused code
intrinsic gas too lowThe gas limit was set manually and is too smallLet the tool estimate gas
replacement transaction underpricedA second transaction reused a nonce without a higher feeRaise the fee by at least the minimum increase required

Contract size limit on this network: [contract size limit]. Supported EVM version: [EVM version].

3.Verification

Verification succeeds only when the explorer can reproduce your exact bytecode. If it fails, compare each of these with your deployment:

  • Compiler version, including the patch number.
  • Optimizer setting and number of runs.
  • EVM version.
  • Linked library addresses.
  • Constructor arguments, ABI-encoded exactly as deployed.
  • Imported file paths and remappings. Flatten the source if the explorer cannot resolve imports.
  • The metadata hash setting. Deploy and verify with the same value.

4.Contract calls

SymptomLikely causeFix
Call reverts with no messageA require without a reason, an unsupported opcode or a wrong addressRun the call in a Foundry fork test with traces, and confirm the address has code
Call returns 0xThe address has no contract on this chainCheck cast code and that you are on the right network
Signature is rejected on-chainWrong chain ID, contract address, nonce or deadline in the signed dataRebuild the EIP-712 domain from the live chain
eth_getLogs returns an errorThe block range is too largeQuery in smaller ranges
Estimated gas is much lower than neededThe call depends on state that changes before the transaction is minedAdd a margin to the estimate and test under load

5.Still stuck

When you ask for help, include the chain ID, the transaction hash, the contract address, the compiler version and settings and the exact error text. Developer support: [developer support contact].

Highlighted items in square brackets are network values that are confirmed and published before the public testnet. Code samples are for learning and are not audited. Have any contract that will hold real value reviewed before launch. The latest version is always on this page, and a PDF copy is available above.