Experiencing issues? This section provides troubleshooting guidance for the following issues:

Installation and Update Issues

I think I need to update the MetaEd IDE.

If you're having trouble with the MetaEd IDE, a good place to start is ensuring you have the latest version. If you're having issues, you may want to skim the What's New section of this documentation to see if the problem you're experiencing is mentioned.

The MetaEd IDE is easy to update. Simply navigate to your MetaEd Atom directory and enter: yarn upgrade atom-metaed.

For details and fine points, see the /wiki/spaces/METAED20/pages/23709737 section of this documentation.

I can't install MetaEd IDE and I receive a warning relating to fetching or downloading packages

A typical error might begin like this: 

Fetching packages... error An unexpected error occurred:...

This can happen on some networks when the VPN or network configuration uses self-signed certificates, which causes SSL issues when attempting to use npm to install software. There are two options to resolve this issue. The easiest is to connect to a new network that does not use self-signed certificates for the install process. The MetaEd IDE will run successfully on either kind of network once it is installed. Another option is to tell Node.js to trust the certificate. You will need to get a copy of the certificate file from your network team, and then set the environment variable NODE_EXTRA_CA_CERTS to the network path to that certificate file. Node.js documentation on this topic is at https://nodejs.org/api/cli.html#cli_node_extra_ca_certs_file. Setting the environment variable in Windows should look something like this:

I just installed/updated the MetaEd IDE and I received a warning about an invalid engine.

You may see a warning message stating "The engine 'atom' appears to be invalid" while installing or updating with Yarn.  This is an interaction between Yarn and Atom that can be safely ignored.

I just updated the MetaEd IDE with "yarn upgrade" and now I'm getting build errors.

If you're having trouble with the MetaEd IDE right after an upgrade to a new version, you may need to upgrade the Yarn installer itself. MetaEd IDE versions that require a Yarn installer upgrade will be indicated in the What's New section for those versions.

Yarn is easy to update. Simply navigate to the Yarn website and download and install the latest version.

You'll now need to undo and redo the upgrade. Navigate to your MetaEd Atom directory and enter yarn upgrade atom-metaed@x.y.z where x.y.z is a recent MetaEd version but not the latest. (If you don't remember any exact versions, just guess. Yarn will provide a list of versions to choose from. Pick a recent one that is not the latest.) Then enter yarn upgrade atom-metaed to upgrade back to the current version.

I want to fully uninstall MetaEd

See the instructions below for "I need a clean installation of MetaEd", but omit the final step.

I need a clean installation of MetaEd.

That happens to the best of us. You can uninstall and start with a fresh installation by following these steps.

Step 1. Restart Your Computer

This is a precautionary step to ensure that any file locks related to Atom or MetaEd are released.

Step 2. Remove Project Folders

In the Atom editor, right-click on each open project folder and click Remove Project Folder. Close Atom.

Step 3. Run the Unlink Command

Open a command prompt and navigate to the MetaEd-IDE folder in your new directory. Type the command apm unlink atom-metaed and press Enter. 

Step 4. Clean MetaEd-IDE Directory

In the directory folder where MetaEd-IDE was initially installed, delete all files and folders other than the files ".yarnrc" and "package.json".

Step 5. Run the Cache Clean Command

Step 6. Uninstall Atom

Open a Control Panel and click Programs and Features. Select Atom and click Uninstall.

Step 7. Delete Atom Directories

Delete the Atom directories in the following locations:

C:\Users\<Username>\.atom

C:\Users\<Username>\AppData\Local\atom

Step 8. Reinstall MetaEd

At this point, all remnants of MetaEd should be expunged. From here, the Download & Installation documentation will help you get back up and running.

I reinstalled MetaEd-IDE but now I have thousands of errors indicating duplication.

When a project folder is deleted from the file directory without removing the folder in the editor, the editor will attempt to open the remaining folder: MetaEd-IDE. In the tree view, you should see an open folder called "MetaEd-IDE" in addition to the usual "ed fi model" folder. Right-click on the MetaEd-IDE folder and click Remove Project Folder. This will remove the folder from the editor but will not delete it from the directory. The error should then resolve.

Error and Warning Issues

There is no syntax highlighting or error detection in my newly created file.

Files must have the extension ".metaed" in the file name in order for MetaEd-IDE to provide syntax highlighting or error detection. If you add a file by clicking "New File" rather than "Add MetaEd File", you must manually add the ".metaed" file extension after the name.

If you've already created the file, you may add the file extension by renaming the file.

I deleted a .metaed file that contained errors. There are no errors in any of the remaining metaed files, but the tree view still shows errors (red underlines).

Error detection only occurs when a file is open. If the only file containing errors is deleted and no remaining files are open in the editor, error detection will not occur to determine that all errors have been cleared. Simply open any file in the editor for the error detection to re-run. The red underlines should then clear.

I corrected all of the errors in a .metaed file, but the red dot persists.

Occasionally, a red dot indicating an error may persist even after the error is corrected and the error count at the bottom displays "0 0 0". Simply close the metaed file in the editor and open it again to dismiss the red dot.

I receive discrepant error messages regarding whether I can include a descriptor in a .metaed file.

The error pictured below seems to indicate that descriptors may be included in domain files, which is incorrect.

Descriptors cannot be included in domain files. The error message above will be corrected in a future release. The error message below provides the correct set of items that may be included in a domain file.

I receive a warning: MetaEdId '3116' on Descriptor Property Term already exists on another entity

Detailed message:

warn: MetaEdId '3116' on Descriptor Property Term already exists on another entity. All MetaEdIds must be globally unique. C:\....\ed-fi-model-3.3b\Common\CohortYear.metaed (9:21)
warn: MetaEdId '3116' on Shared Decimal Property EarnedCredits already exists on another entity. All MetaEdIds must be globally unique. C:\....\ed-fi-model-3.3b\Common\PartialCourseTranscriptAwards.metaed (6:53)

The MetaEdId is an optional feature, primarily used only by the Alliance. This warning indicates that a value was accidentally re-used in model 3.3b. This will not have any detrimental impact on an extension build and should be ignored.

File and Folder Issues

I moved a .metaed file to a new folder, but it keeps showing up in the old location.

If a metaed file is open in the editor when a file is moved, the open tab will continue to point to the former location. If you save the open tab after the move, the editor will save a copy of the file in the former location. You may avoid this by closing the editor tab before moving the file or by closing the file without saving the changes after the file has been moved.

I renamed a .metaed file, but a duplicate keeps appearing with the old file name.

If a metaed file is open in the editor when a file is moved, the open tab keeps the former path. If you save the open tab after renaming the file, the editor will save a copy of the file with the former name. You may avoid this by closing the editor tab before changing the file name or by closing the file without saving the changes after the file has been renamed.

I right-click on a file/folder, click "Rename", and type the new file name but the file is not renamed.

A file/folder name is only saved by pressing "Enter" after typing the new path. Clicking anywhere on the page will not save the file name.

Data Modeling Issues

I have a complex data model that requires multiple references to resolve to a single entity.

A complex model can result in duplicate references flowing through the model. Sometimes, your model may require that the references always be a merged reference to a single entity, rather than multiple references to the same type of entity with different roles. MetaEd can handle these complex modeling scenarios by using the merge...with directive.

See the MetaEd Cookbook entry Using Merge Directives for details.

Build and Deploy Issues

I ran a successful build, but re-running the build now results in an "Unable to delete output directory..." error.

Unable to delete output directory at path "C:\...\MetaEdOutput\". 
Please close any files or folders that may be open in other applications.

First, double-check that you do not have any of the MetaEd output files open in any other application. Antivirus protection software may place a file-lock on MetaEd output files preventing the MetaEd IDE from deleting the output from the previous build to replace with output from the new build. If all output files are closed and you still receive this error, you may need to update the settings on your antivirus protection to prevent the file-lock from occurring. Restarting your computer will also remove the file-lock and allow the IDE to delete and replace the output files.

I ran a build and received an error, but I can't tell if MetaEd IDE has completed the attempt. 

If an error is encountered during a build attempt, MetaEd IDE will not provide any other indication that the build attempt has completed other than a description of the error that caused the build to fail. The error message itself is an indication that the attempt has finished.

No errors are detected in the .metaed files before the build, but running a build results in an "extraneous input" error.

error: extraneous input 'Extraneous' expecting {'Abstract Entity', 'Association', 'End Namespace', 'Choice', 'Common', 'Descriptor', 'Domain', 'Domain Entity', 'Enumeration', 'Interchange', 'Inline Common', 'Shared Decimal', 'Shared Integer', 'Shared Short', 'Shared String', 'Subdomain'}

The editor currently does not detect extra text inserted at the end of a domain file. The linter will not show any errors, but the build will still fail. Simply remove the extraneous text at the end of the domain file(s) and run the build again.

The Interchange XSD files generated by the build are invalid when opened in an XML editor.

In order to assist with file organization, build artifacts are sorted into folders according to the type of artifact.

However, the schema location specified in the generated interchange files expects the schema file to be in the same folder as the interchange files. Simply move either the schema file or the interchange files (or both) into the same folder. 

Your interchange files should now validate properly in an XML editor.

If you make additional changes and run the build again, all MetaEdOutput folders are deleted and replaced in their original locations. Therefore, to validate the interchange files in an XML editor after a new build, they will need to be manually moved again.

Additional Resources

I'd like to get in touch with a human about MetaEd.

MetaEd questions, bugs, issues, and feature recommendations are tracked via the general Ed-Fi Project in the Ed-Fi Tracker / JIRA system. You can submit a ticket here, and a human will get back with you.