Gli errori di compilazione VBA in Microsoft Access possono bloccare l’apertura di una maschera, impedire l’esecuzione di una macro che richiama una funzione, interrompere un report o rendere inutilizzabile un database che fino al giorno prima funzionava senza problemi. Il punto importante è capire che un errore di compilazione VBA non è la stessa cosa di un errore che avviene durante l’esecuzione: la compilazione controlla se il progetto VBA può essere trasformato in codice eseguibile coerente, mentre un errore runtime si verifica quando il codice è già partito e incontra una condizione problematica.
In questa guida vediamo come diagnosticare e risolvere in modo sistematico gli errori di compilazione in Access, con particolare attenzione ai casi più comuni: riferimenti mancanti, nomi non riconosciuti, variabili non dichiarate, procedure duplicate, errori di sintassi, funzioni non disponibili, librerie COM mancanti, incompatibilità tra Office a 32 e 64 bit, istruzioni Declare non aggiornate, problemi con PtrSafe e LongPtr, database ACCDE e differenze tra Access completo e Access Runtime.
Le indicazioni valgono per Access incluso in Microsoft 365 e per Access 2024 su Windows. Access rimane un’applicazione desktop Windows: non esiste una versione nativa completa di Access per macOS e il codice VBA di un database Access non viene eseguito nel browser come una normale applicazione Web.
Per approfondire gli argomenti collegati puoi consultare anche come fare debug del codice VBA in Access, come risolvere gli errori VBA in Microsoft Access, come correggere i riferimenti mancanti in Access e la raccolta completa delle Guide Microsoft Access.
Che cos’è un errore di compilazione VBA in Access
Quando apri l’editor VBA con Alt+F11 e scegli Debug > Compila seguito dal nome del progetto, Access chiede al motore VBA di controllare l’intero progetto. Il compilatore analizza moduli standard, moduli di classe, codice associato a maschere e report, dichiarazioni, riferimenti alle librerie, chiamate di funzione, tipi di dati e altre dipendenze necessarie.
Se trova un problema che impedisce di interpretare correttamente il codice, interrompe la compilazione e mostra un messaggio. Alcuni esempi frequenti sono “Errore di compilazione: variabile non definita”, “Sub o Function non definita”, “Tipo definito dall’utente non definito”, “Nome ambiguo rilevato”, “Previsto: fine istruzione”, oppure il messaggio relativo al codice che deve essere aggiornato per sistemi a 64 bit.
È essenziale non limitarsi a chiudere il messaggio. In molti casi VBA evidenzia direttamente la parola o la riga che ha provocato l’errore. Quell’evidenziazione è il primo indizio da analizzare. Tuttavia la riga segnalata non sempre rappresenta la causa originaria: un riferimento mancante a una libreria, per esempio, può far apparire non riconosciuta una funzione standard che in realtà è corretta.
Prima di modificare il codice: crea una copia del database
Prima di intervenire su un database importante, esegui una copia di sicurezza del file. Questo vale soprattutto quando devi cambiare riferimenti, dichiarazioni API, moduli condivisi o codice utilizzato in molte maschere. Se il database è diviso in front-end e back-end, per correggere errori di compilazione del VBA di solito si lavora sul front-end, ma è comunque opportuno sapere dove risiedono i dati e conservare una copia coerente dell’ambiente.
Evita di effettuare modifiche strutturali direttamente sull’unica copia distribuita agli utenti. In un ambiente multiutente è preferibile correggere e testare un front-end di sviluppo, compilarlo, provarlo su un PC rappresentativo e soltanto dopo distribuire la versione corretta. Se l’applicazione finale viene consegnata come ACCDE, conserva sempre il file sorgente ACCDB: un ACCDE non è il formato da utilizzare come unica copia di sviluppo.
Procedura di diagnosi: come trovare il primo errore reale
1. Apri l’editor VBA
Apri il database con la versione completa di Microsoft Access, quindi premi Alt+F11. Se stai utilizzando soltanto Access Runtime, ricorda che Runtime è pensato per eseguire un’applicazione distribuita e non offre lo stesso ambiente di sviluppo della versione completa. Per diagnosticare e correggere il progetto VBA serve quindi una postazione con Access completo.
2. Controlla i riferimenti prima di compilare
Nell’editor VBA apri Strumenti > Riferimenti. Cerca voci contrassegnate come MANCANTE o MISSING. Un riferimento non disponibile può provocare errori apparentemente scollegati dalla libreria mancante. Per esempio, una funzione che prima veniva risolta correttamente può improvvisamente essere segnalata come non definita.
Se trovi un riferimento mancante, non selezionare a caso una libreria con un nome simile. Devi identificare quale componente utilizzava realmente il progetto, se è ancora necessario e se esiste una versione compatibile installata sul computer. Per componenti COM o ActiveX può essere necessario installare la versione corretta del software o del driver. In altri casi il riferimento può essere eliminato se il relativo codice non viene più usato.
3. Esegui Debug > Compila
Dopo aver sistemato i riferimenti, scegli Debug > Compila. Risolvi il primo errore mostrato, quindi ripeti la compilazione. Non cercare di correggere contemporaneamente decine di righe basandoti solo sull’intuizione. La compilazione progressiva è più affidabile: un singolo problema iniziale può generare una cascata di messaggi secondari che scompaiono automaticamente quando viene eliminata la causa principale.
4. Salva, chiudi e riapri
Quando la compilazione termina senza errori, salva il progetto. Nei casi più complessi è utile chiudere Access e riaprire il database per verificare che il progetto venga caricato correttamente da zero. Esegui poi le funzioni principali dell’applicazione, perché compilare senza errori è necessario ma non garantisce che la logica produca risultati corretti durante l’esecuzione.
Errore “Variabile non definita”
Questo errore compare tipicamente quando nel modulo è presente Option Explicit e il codice utilizza un identificatore che non è stato dichiarato. L’uso di Option Explicit è una buona pratica perché impedisce che un semplice errore di battitura generi implicitamente una nuova variabile Variant.
Considera questo esempio: Option Explicit : Sub CalcolaTotale() : Dim Totale As Currency : Totlae = 125.50 : MsgBox Totale : End Sub. La variabile dichiarata è Totale, ma nella riga successiva è stato scritto Totlae. Con Option Explicit il compilatore segnala immediatamente il problema. Senza questa direttiva, VBA potrebbe creare una nuova variabile Variant chiamata Totlae, lasciando Totale a zero e producendo un risultato logico sbagliato molto più difficile da individuare.
La soluzione corretta non consiste quindi nel rimuovere Option Explicit, ma nel correggere il nome o dichiarare esplicitamente la variabile necessaria. Nell’editor VBA puoi attivare la dichiarazione obbligatoria per i nuovi moduli tramite Strumenti > Opzioni > Richiedi dichiarazione variabili.
Errore “Sub o Function non definita”
Il messaggio indica che VBA non riesce a trovare una procedura o funzione chiamata dal codice. Le cause possono essere diverse: nome digitato in modo errato, funzione privata chiamata da un modulo che non può accedervi, modulo eliminato, riferimento mancante, libreria esterna non disponibile oppure funzione personalizzata rinominata.
Se il codice contiene Private Sub cmdStampa_Click(): GeneraReportMensile: End Sub, deve esistere una procedura accessibile con quel nome, per esempio Public Sub GeneraReportMensile(): DoCmd.OpenReport "rptMensile", acViewPreview: End Sub. Controlla che non ci siano differenze di ortografia, che la procedura non sia stata dichiarata Private in un modulo inaccessibile e che il modulo standard non abbia lo stesso nome della procedura in modo da creare ambiguità. Se il nome riguarda una funzione fornita da una libreria esterna, torna invece al controllo dei riferimenti.
Errore “Tipo definito dall’utente non definito”
Questo errore si presenta spesso quando il codice dichiara un oggetto appartenente a una libreria che non è disponibile o non è referenziata. Un vecchio progetto potrebbe, per esempio, utilizzare tipi DAO, ADO, Outlook, Excel o componenti di terze parti. Il codice Dim rs As DAO.Recordset richiede che il progetto possa risolvere il tipo DAO.Recordset. Nei database Access moderni DAO è normalmente parte dell’ambiente Access Database Engine, ma un riferimento danneggiato o un progetto migrato può comunque generare problemi.
Per automazioni verso applicazioni Office puoi scegliere tra early binding e late binding. Con early binding si aggiunge il riferimento alla libreria specifica e si dichiarano tipi concreti, ottenendo IntelliSense e controlli in fase di compilazione. Con late binding si usano oggetti generici creati a runtime, riducendo alcune dipendenze di versione ma rinunciando al controllo anticipato dei tipi. Non esiste una scelta universalmente migliore: dipende da distribuzione, compatibilità e manutenzione.
Errore “Nome ambiguo rilevato”
Questo messaggio indica normalmente che il progetto contiene due procedure, funzioni o membri con un nome che VBA non riesce a distinguere nel contesto corrente. Un caso tipico è la duplicazione accidentale di un evento in un modulo di maschera. Access non può avere due procedure Form_Load identiche nello stesso modulo. Devi unire la logica in un’unica procedura oppure rinominare la routine se non rappresenta lo stesso evento. Il problema può comparire anche con funzioni pubbliche duplicate in moduli standard differenti. In quel caso valuta nomi più specifici e una struttura modulare coerente.
Errori di sintassi e “Previsto: fine istruzione”
Gli errori di sintassi derivano da istruzioni che non rispettano la grammatica VBA: parentesi mancanti, virgolette non chiuse, operatori errati, continuazioni di riga incomplete, blocchi If o Select Case non terminati, dichiarazioni posizionate in modo scorretto. Un errore frequente riguarda stringhe SQL costruite concatenando valori. È importante distinguere compilazione e runtime: una stringa può essere sintatticamente valida per VBA e contenere però SQL non valido che fallisce soltanto quando viene eseguito.
Per query complesse è spesso preferibile utilizzare query parametrizzate o QueryDef con parametri, riducendo sia gli errori di quoting sia i rischi legati a input non controllati. Inoltre, se il problema compare in una query salvata, esegui la query direttamente dall’interfaccia di Access per separare un eventuale errore SQL da un problema VBA.
Compatibilità VBA tra Office 32 bit e 64 bit
Uno dei motivi più comuni per cui un vecchio database Access compila su un computer e fallisce su un altro è il passaggio da Office a 32 bit a Office a 64 bit. La documentazione Microsoft spiega che le istruzioni Declare che chiamano funzioni delle API Windows devono essere aggiornate per l’ambiente VBA7 e che, sulle versioni a 64 bit di Office, è necessario utilizzare PtrSafe. Microsoft precisa inoltre che aggiungere semplicemente PtrSafe non rende automaticamente corretta la dichiarazione: parametri e valori di ritorno che rappresentano puntatori o handle devono usare tipi in grado di contenere valori a 64 bit, tipicamente LongPtr.
La documentazione ufficiale è disponibile in 64-bit Visual Basic for Applications overview e nella pagina Microsoft sulla compatibilità tra Office 32 e 64 bit.
Un esempio di Declare da aggiornare
Un vecchio codice potrebbe contenere Private Declare Function GetActiveWindow Lib "user32" () As Long. Su Office a 64 bit questa dichiarazione non è corretta. Un esempio aggiornato per VBA7 è Private Declare PtrSafe Function GetActiveWindow Lib "user32" () As LongPtr. PtrSafe dichiara che la firma è stata revisionata per l’ambiente a 64 bit, mentre LongPtr è un alias che si adatta alla piattaforma.
Non sostituire però ogni Long con LongPtr indiscriminatamente. Long continua a essere un intero a 32 bit e rimane corretto per moltissimi parametri che non rappresentano puntatori o handle. La regola è comprendere il significato del parametro dell’API e applicare il tipo corretto, non effettuare una sostituzione globale.
Uso delle costanti di compilazione
Quando serve mantenere compatibilità con ambienti differenti, puoi incontrare codice condizionale con #If VBA7 Then e un ramo alternativo per versioni più vecchie. In un ambiente moderno basato su Access Microsoft 365 o Access 2024 stai lavorando con VBA7, ma il codice condizionale può essere utile se il progetto ha una lunga storia e deve rimanere compatibile con distribuzioni legacy. Per distinguere specificamente l’architettura puoi inoltre incontrare la costante Win64.
Prima di modificare questi blocchi, comprendi che cosa rappresentano realmente i parametri dell’API: copiare firme trovate online senza verificare la documentazione può introdurre crash o risultati errati. Per le API Windows affidati alla documentazione Microsoft e verifica in particolare handle, puntatori, callback e strutture definite dall’utente.
Perché un riferimento mancante può provocare errori strani
Quando una libreria referenziata non è disponibile, il compilatore può perdere la capacità di risolvere tipi e funzioni. A volte l’errore viene mostrato proprio sulla funzione della libreria; altre volte il progetto sembra rompersi in un punto insospettabile. Per questo il controllo di Strumenti > Riferimenti deve essere tra i primi passaggi di qualsiasi diagnosi.
Se il database è stato spostato da un altro PC, verifica anche l’architettura dei componenti esterni. Un controllo ActiveX o un provider ODBC disponibile soltanto a 32 bit non diventa automaticamente compatibile perché Access è stato installato a 64 bit. Driver, provider e componenti caricati nel processo di Access devono essere compatibili con l’architettura dell’applicazione che li utilizza.
ACCDE e errori di compilazione
Il formato ACCDE è utile per distribuire un’applicazione Access impedendo agli utenti di modificare il codice sorgente VBA e alcuni oggetti di progettazione. Tuttavia la creazione dell’ACCDE richiede che il progetto sia compilabile. Se il comando per generare l’ACCDE fallisce, la prima operazione da fare è aprire l’ACCDB sorgente, compilare manualmente il progetto e correggere ogni errore.
Un’altra variabile è l’architettura. Un ACCDE compilato in un determinato ambiente può avere vincoli di compatibilità maggiori rispetto all’ACCDB sorgente, soprattutto quando contiene codice e componenti dipendenti dalla piattaforma. Se distribuisci l’applicazione su PC misti, standardizzare la versione e l’architettura di Office riduce notevolmente i problemi operativi. Non usare mai l’ACCDE come unica copia del progetto: conserva l’ACCDB sorgente con backup datati.
Access Runtime: cosa cambia
Microsoft Access Runtime permette di eseguire applicazioni Access su PC che non dispongono della versione completa di Access, entro i limiti previsti dal Runtime. Questo non significa che Runtime sia un sostituto dell’ambiente di sviluppo. Se un’applicazione distribuita tramite Runtime presenta un errore di compilazione, la correzione deve essere fatta nell’ACCDB sorgente usando Access completo, quindi la versione corretta deve essere ridistribuita.
Prima del rilascio prova il front-end su un computer rappresentativo con la stessa architettura Office prevista per gli utenti. Verifica apertura, maschere di avvio, report, esportazioni, chiamate API, automazioni verso Excel o Outlook, driver ODBC e librerie esterne. Un progetto che compila sul PC dello sviluppatore può comunque fallire su un client se gli manca una dipendenza.
Come diagnosticare una compilazione che fallisce solo su alcuni PC
Quando lo stesso file funziona su un PC e non su un altro, evita di modificare subito il codice. Prima confronta gli ambienti. Controlla versione di Access, bitness 32/64, aggiornamenti Office, riferimenti, driver ODBC, componenti COM/ActiveX, percorsi di file esterni, Trusted Locations e autorizzazioni.
Una checklist utile comprende versione di Windows, versione di Microsoft 365 o Access 2024, Access 32 o 64 bit, elenco dei riferimenti VBA con versione, presenza di controlli ActiveX, provider ACE/ODBC richiesti, eventuali DLL di terze parti, percorso del front-end e percorso delle tabelle collegate. Documentare queste informazioni evita molte diagnosi basate su tentativi casuali.
Compilazione dopo l’importazione di oggetti da un altro database
Importare moduli, maschere o report da un altro ACCDB può introdurre dipendenze che nel database di destinazione non esistono. Dopo ogni importazione significativa, controlla i riferimenti e compila subito. Se rimandi il test, potresti scoprire settimane dopo che una maschera apparentemente funzionante contiene codice che richiama una funzione mancante.
Lo stesso vale quando copi manualmente un modulo VBA. Il modulo può dipendere da una funzione pubblica situata in un altro modulo, da una query salvata, da una tabella, da un riferimento COM o da una costante definita altrove. Copiare solo il blocco visibile non significa aver copiato l’intera dipendenza.
Un metodo pratico per isolare il problema
Se il progetto è molto grande e l’errore non è immediatamente comprensibile, lavora per esclusione. Crea una copia del front-end, compila e annota l’errore. Verifica i riferimenti. Controlla la riga evidenziata e le procedure chiamate. Se una dipendenza esterna è sospetta, prova su un ambiente in cui quella dipendenza è sicuramente installata. Se l’errore riguarda codice importato di recente, confronta il modulo con la versione precedente funzionante.
Per database professionali è utile mantenere un changelog. Sapere che il problema è comparso dopo l’installazione di Office 64 bit, dopo la sostituzione di un PC o dopo l’aggiornamento di una libreria riduce enormemente lo spazio di ricerca. Registra anche le versioni dei driver e dei componenti esterni.
Errori di compilazione dopo un aggiornamento di Office
Gli aggiornamenti di Microsoft 365 possono modificare componenti, correggere bug o cambiare il comportamento di elementi esterni al tuo progetto. Non significa che ogni errore successivo a un aggiornamento sia causato direttamente dall’aggiornamento, ma la coincidenza temporale è un dato da registrare. Se molti PC funzionano e uno solo no, confronta prima quel client con gli altri. Se tutti iniziano a fallire nello stesso momento, esamina invece dipendenze e modifiche comuni.
Evita di risolvere un problema di compatibilità disabilitando in modo permanente gli aggiornamenti. È molto più sostenibile correggere codice legacy e dipendenze obsolete. In particolare, per le API Windows Microsoft documenta chiaramente il modello PtrSafe/LongPtr per Office a 64 bit.
Errori di compilazione e sicurezza delle macro
Un progetto VBA bloccato dalle impostazioni di sicurezza non presenta necessariamente lo stesso comportamento di un progetto con errori di compilazione. Se Access mostra avvisi di contenuto o impedisce l’esecuzione di codice non attendibile, verifica il Centro protezione, le Trusted Locations e le firme digitali previste dalla tua organizzazione. Non abbassare globalmente la sicurezza per far funzionare il database.
In un ambiente aziendale è preferibile distribuire il front-end da una posizione controllata, firmare il codice quando la governance lo richiede e utilizzare percorsi attendibili gestiti dall’amministratore. Runtime e ACCDE non costituiscono da soli una barriera di sicurezza contro ogni tipo di manomissione o accesso ai dati.
Quando usare Compatta e ripristina
Compatta e ripristina database può essere utile per manutenzione e alcuni problemi del file, ma non è la soluzione universale agli errori di compilazione VBA. Se il compilatore segnala una variabile non definita, una funzione mancante o una dichiarazione API incompatibile, la causa è nel progetto o nelle dipendenze e deve essere corretta lì.
Se sospetti invece un danneggiamento del file, crea prima una copia e segui una procedura di recupero prudente. Non sovrascrivere l’unico originale con tentativi ripetuti. Dopo il recupero, compila nuovamente il progetto per verificare che i moduli siano coerenti.
Procedura di controllo prima del rilascio
Supponiamo di avere un gestionale Access diviso in front-end e back-end. Prima di distribuire una nuova versione del front-end crea una copia dell’ACCDB sorgente, apri l’editor VBA, controlla Strumenti > Riferimenti, esegui Debug > Compila finché non restano errori, controlla ogni Declare usato con API Windows e verifica la compatibilità 32/64 bit.
Poi prova l’applicazione con dati di test, apri maschere principali, report ed esportazioni, verifica tabelle collegate e connessioni ODBC e testa su un secondo PC con configurazione equivalente a quella degli utenti. Solo dopo genera l’eventuale ACCDE e distribuisci il front-end mantenendo una procedura di rollback. Questo approccio riduce la probabilità di scoprire un errore di compilazione direttamente sul computer di un utente.
FAQ sugli errori di compilazione VBA in Access
Perché Access mostra un errore di compilazione appena apro il database?
Probabilmente una maschera di avvio, una macro AutoExec o un evento iniziale richiama codice che non compila. Se possibile evita l’avvio automatico, apri l’editor VBA, controlla i riferimenti ed esegui la compilazione manuale.
Un riferimento MISSING può bloccare tutto il progetto?
Sì. Un riferimento mancante può impedire la risoluzione di tipi e funzioni e produrre messaggi anche in righe apparentemente corrette. Risolvi i riferimenti prima di correggere errori secondari.
Devo sostituire tutti i Long con LongPtr su Office 64 bit?
No. Microsoft specifica che LongPtr serve per valori che rappresentano puntatori e handle. Long resta un intero a 32 bit valido. La modifica indiscriminata dei tipi può creare nuovi problemi.
Basta aggiungere PtrSafe a ogni Declare?
No. PtrSafe dichiara che la firma è stata resa compatibile, ma devi anche verificare i parametri e i valori di ritorno che contengono puntatori o handle e usare i tipi appropriati. La documentazione Microsoft sottolinea esplicitamente questo punto.
Un database compilato su Access 32 bit funzionerà sempre su Access 64 bit?
Non necessariamente. Codice VBA puramente logico può essere portabile, ma API Windows, ActiveX, provider e componenti esterni possono dipendere dall’architettura. Il progetto deve essere testato sull’ambiente reale di destinazione.
Access 2024 e Access Microsoft 365 usano VBA?
Sì, entrambe le edizioni desktop Windows supportano VBA. Microsoft 365 riceve aggiornamenti continui secondo il canale configurato, mentre Access 2024 è una versione perpetua. In entrambi i casi le considerazioni sulla bitness di Office e sulle dipendenze esterne restano rilevanti.
Posso correggere il VBA con Access Runtime?
Runtime è destinato all’esecuzione delle applicazioni, non allo sviluppo completo. Per diagnosticare, modificare e compilare il codice è opportuno utilizzare Microsoft Access completo.
Perché il comando Compila non è disponibile?
Può risultare non selezionabile se il progetto è già compilato e non ha modifiche da ricompilare. Modificare e salvare il codice rende nuovamente necessaria la compilazione. Se invece il progetto è protetto o stai lavorando su un ACCDE, potresti non avere accesso al sorgente modificabile.
Posso ignorare un errore di compilazione se l’applicazione sembra funzionare?
È una cattiva pratica. Alcune procedure potrebbero non essere ancora state richiamate e il problema potrebbe emergere soltanto in una funzione specifica. Prima di distribuire un front-end, il progetto dovrebbe compilare senza errori.
Conclusione
Risolvere gli errori di compilazione VBA in Access richiede un metodo ordinato: backup del front-end, controllo dei riferimenti, compilazione manuale, correzione del primo errore reale, verifica delle dipendenze e test sull’architettura di destinazione. Gli errori più semplici derivano da nomi o sintassi; quelli più insidiosi riguardano librerie mancanti e differenze tra Office 32 e 64 bit.
Quando il database contiene chiamate alle API Windows, non limitarti ad aggiungere PtrSafe: verifica anche quali parametri sono realmente puntatori o handle e usa LongPtr dove appropriato, seguendo la documentazione Microsoft. In ambienti multiutente o con Runtime, correggi sempre il sorgente ACCDB in un ambiente di sviluppo separato e distribuisci soltanto una versione compilata e testata.
Per continuare l’approfondimento consulta le altre Guide Access di Guide-Pratiche.it, dove trovi procedure dedicate a debug VBA, riferimenti mancanti, distribuzione, Runtime, ACCDE, tabelle collegate, backup e manutenzione.