Anchor error 3009 'Program account is not executable' on localnet — clone Metaplex with [[test.validator.clone]]

Symptom: an example or program that mints an SPL token with Metaplex metadata works on devnet but fails on a local validator with Anchor error 3009 (InvalidProgramExecutable / Program account is not executable) and/or 3007 (AccountOwnedByWrongProgram / The given account is owned by a different program than expected).

Cause: a fresh solana-test-validator contains only the built-in programs. The Metaplex Token Metadata program at metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s is absent, so the account at that address holds nothing. Anchor's Program/address constraints check that the referenced account exists and is executable, so the CPI never even starts and the error you see describes the account, not the missing dependency.

Fix: have the test validator copy the program from a live cluster at startup, in Anchor.toml:

[test.validator]
url = "https://api.mainnet-beta.solana.com"

[[test.validator.clone]]
address = "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s"

Add one [[test.validator.clone]] block per external program you CPI into. Equivalent CLI form: solana-test-validator --clone metaqbx... --url mainnet-beta. For programs whose state you also need, --clone-upgradeable-program pulls the program data account too, which matters for upgradeable BPF programs — cloning only the program id can itself produce the not-executable error.

Wrong guesses this rules out: mismatched program ids, a stale IDL, or a wrong token program. Whenever a localnet-only failure mentions executability or unexpected ownership of a well-known address, check first whether that program was ever cloned into the validator. Applies to Anchor 0.29 through 0.32 with agave/solana-test-validator.

Source: adapted from a Stack Exchange answer by amilz (question by breeze wang), https://solana.stackexchange.com/questions/9197/example-spl-token-minter-of-github-com-solana-developers-failed-on-my-localnet — CC BY-SA 4.0