Reporting Mod Errors

From TNG_Wiki
Jump to: navigation, search

When you download a mod and copy it to your mods folder, you hope, and generally assume, that is will show the status "Ok to Install" in the Mod Manager. But sometimes it doesn't. When your mod has a status other than "Ok to Install" (and there are several possibilities), you need to understand the nature of the problem, and ultimately, you may need to report the conflict to one or mod more authors.

First you need to expand the status column to find why the mod shows a Cannot Install status. Reporting a Cannot Install issue on the TNG Community Forum or on the TNG user2list, only causes unnecessary emails for you to expand the status to find the error being reported.

Second, be sure that you understand the information in the article Mod Manager - Interpreting Status. It describes the various mod status and target location status, and suggests resolution options for each status.

Most Common Cannot Install

The following are some of the most common reasons for a mod error status of "Cannot Install", which is a mod status that occurs when target locations in a mod's .cfg file report

  • Bad Target errors caused by trying to install the wrong version of a mod. See TNG Mod Version Numbers for Beginners on how to determine what mod version you need
  • Bad Target errors because the cust_text.php was not updated to the current Mod Guidelines for the custom text anchors in TNG v12 and V13
  • Source missing errors because the mod zip file contains a subfolder and the contents of the folder was transferred to the mods folder directly instead of being transferred as a subfolder to the mods folder with all the contents remaining in the subfolder
  • Syntax errors which might occur on a PHP upgrade that changed the rules
  • Bad Target errors caused by source changes or a conflict with another mod

It is important to note that the mod with "Bad target" errors is not necessarily at fault in the conflict. If you had installed the mod with "Bad target" errors before you installed the (not yet known) conflicting mod, well, then the other mod would report "Bad target" errors. Thus, when you find "Bad target" errors and resulting "Cannot install" mod status, it is important that you investigate your mods to try to find the other mod(s) involved in the conflict(s). If you can determine what those other mods are, you can decide which mod author to contact, or you can contact both (or all, if multiple mods are involved).

Syntax Errors

In some cases, a mod status of "Cannot Install" is caused by syntax errors within the mod's .cfg file. Syntax errors are generally reported succinctly, like this:
Reporting mod installation conflicts-syntax.jpg


You may be able to fix syntax error on your own, but, in any case, you should report syntax errors to the mod author through the "Mod Support" or "Contact Developer" links in the mod information sidebar of the mod's Wiki article.

Source Missing

This error is reported when a file that a mod wants to copy to an active TNG folder is not in the mod's subfolder:
Reporting mod installation conflicts-missing.jpg

In response to this error, you should check the zip file you downloaded, and make sure that you have copied all files and subfolders into you mods folder. If the file is truly missing, then you should report this error to the mod author, as above, through the "Mod Support" or "Contact Developer" links in the mod information sidebar of the mod's Wiki article.

Note that the common error that causes source missing errors is that you copied the mod subfolder contents to the mods folder rather than copying the subfolder with its contents to the mods folder as a subfolder

Bad Target

Here is a mod that reports two Bad target errors in one target file, and another Bad target error in a different file.
Reporting mod installation conflicts-badtarget.jpg


Bad Targets indicate that the code in the specified line specified of the mod cfg file does not match the code at any location within the targeted file.

There are at least a couple of sources of "Bad target" errors

Prerequisite Mods

Some mods require that another mod be installed first, and may report "Bad target" in one or more target locations if the prerequisite mod is missing. These "Bad target" errors look like mod conflicts, and can only be distinguished from mod conflicts through

  1. An error description that the mod author associates with an anticipated "Bad target" error in a specific target location. This kind of description was enabled only with TNGv12, and is not yet commonly used,
  2. A mod note that is shown in the un-expanded Mod Manager status cell. This kind of description is a great idea, but again, mod notes are not as widely used by mod authors as they could be.
  3. Text within the mod description that is shown in the expanded status cell. This kind of description should always be present.
  4. Documentation in the mod's Wiki article. This description is fundamental; it should always be present.

If any of these sources tell you that a specific mod needs to be installed, well, install it. Otherwise, well, one way or another, you have to treat the errors as a mod conflict.

cust_text.php not updated

TNG v12 Mod Guidelines changed the required anchor for adding custom text to the languages cust_text.php files to place the mod custom text before


//Mods should put their changes before this line, local changes should come after it.

Therefore if the Bad Target is on a languages /cust_text.php file, you should go the the Mod Manager Recommended Actions tab and update the cust_text.php files. If the Recommended Actions tab is not shown, the instructions at the top of the TNG Wiki article on the mod should provide instructions on how to do the updates.

Mod Conflicts

Generally, "Bad target" errors that at least one installed mod on your site has modified

  • The target location search text, or
  • The target location replacement text (when the target location uses a %replace:% or %trimreplace:directiveAt least for the target location, that reports the error that the mod that reports the Bad error uses to

Conflict Documentation

The first step to figuring out what has caused a "Bad target" error is to look for documentation of known conflicts, generally in the mod's Wiki article.

There are so many TNG mods that it is impossible or impractical for mod authors to anticipate all mod conflicts for all mods, but mod authors can do generally download at least some other mods that edit the same files, check for "Bad target" errors, and document those conflicts in the mod's Wiki article. If there are few enough conflicts, it can also be practical for the mod author also to document the conflicts in the mod's Mod Manager description. But conflicts other than missing prerequisites are very rarely reported through target location description or mod notes.

If you find documentation of a mod conflict, you can hope that the documentation explains

  • How to resolve the conflict,
  • Whether one conflicting mod turns out to implement some features of the other mod, or
  • If there is a third mod that implements features from one mod or the other and does not conflict with the other mod.

When the conflict is documented, but no explanation is presented, you may decide that it is reasonable to contact one or both mod authors to request that they try to resolve the conflict, or you may just need to keep one of the mods and (uninstall if necessary and) delete the other.

Which mod is in conflict

Absent documentation of a mod conflict, you should try to figure out which of your installed mods is conflict with the mod that reported the "Bad target" error(s) before you report the error. After all, if the mod conflict is not already documented, the mod author doesn't know about it, and your mods are the key to resolving the conflict.

The Mod Analyzer

The Mod Analyzer is a Mod Manager tool that is specifically intended to help you figure out which of your mods are in conflict with the mod that reported the "Bad target" errors. See the Wiki article Using the Mod Analyzer to learn how to run the Mod Analyzer to determine which of your mods change the same files as the first mod. Then you need to follow a process to narrow that list to mods that are clearly in conflict with the first mod.

Narrowing the List

If the first mod had Bad target errors in more than one file, you'll need to run the Analyzer against each file, and merge the lists to get a single list of candidate mods.

Then take the list of candidate mods, and, for each mod that is installed,

  1. Uninstall the mod
  2. Look at the mod listing for the first mod to see whether any of the Bad target errors have been resolved
    • If some of the errors have been resolved, then you have found a conflicting mod.
    • If the first mod now shows "OK to Install", then you have found the conflicting mod, and you can stop searching.
  3. Reinstall the mod

If this process cannot identify specific mods that are in conflict, well, then there probably isn't a mod conflict; it's probably just an error in the mod that somehow escaped the author's testing. You should report the problem, note that uninstalling your mods did not resolve the conflict, but still submit the list of mods that your mods resolved you'll need to list all of the mods th, then conflict with the If you cannot find documentation that describes a conflict TNG Wiki does have a way to keep track of which mods edit a given files, but those file-specific "Category pages" are lists of for mod articles to add themselves to "category pages" for TNG files that report which mods edit way for mod mod Wiki article to add their mod to report their files which files they edit, and mod authors should check their mods against at least some of the mods in their target files

How to Report Errors

This section applies to all of the circumstances described above where it is suggested that you contact the mod author. You'll find information below about what to report.

The first place to go is to the sidebar of the mod's Wiki article, where you should find hyperlinks next to the "Mod Support" and "Contact Developer" links. Those to items are virtually redundant, and are likely to have the same links, but if they are different, it's probably best to follow the "Mod Support" link. One or both of the links will probably take you to a problem reporting form similar to this:
Reporting mod installation conflicts-supportform.jpg

It's not unheard of for mod developers to fade away from TNG, in which case you may find that the Mod Support form is not accessible, that it may not work, or that (after a reasonable amount of time) you do not get a response. If that happens, move on to the next way to contact the mod author.

Second - "Mod Support" and "Contact Developer" links in the Wiki article may provide more than one option. If the Wiki article points you to "The TNG Community" or "TNG Forums", then you should go to the TNG Community Forum, log in, and post a message in the Question and Answers forum. (If you do not have an TNG Community forum account, request one, and you should get a reply quickly.) Your message should include most of the information requested in the mod support form shown above, plus the information described below. Ideally, you should try to direct your message to the mod author by looking the author in the TNG Community user list and "inviting' the author into the message thread that you are starting. Inviting the author will not limit who else will see your message.

Third - Once you have exhausted the "Mod Support" and "Contact Developer" links, then follow the mod author link in the Wiki article sidebar or in the expanded Mod Manager status cell. That link will probably not take you directly to an email form, but it should take you to a web page (typically, the author's personal page on the TNG Wiki) that is likely to provide a contact list. That link might just be the support form you've already seen, but it may be new.

Fourth- If you didn't use the TNG Community in second step above, well, try it now.

Fifth - Try the TNGusers2 discussion list. It has a larger audience than the TNG Community forum, so you might get a better response from the discussion list than from the forum, but, of course, your discussion list posting will be pushed to many people who are not in a position to respond. If you are not a member of the discussion list, then you can go to the discussion list subscription page.

Significantly, even though the audience of the TNG Community forum is smaller than the audience of the discussion list, several very knowledgeable and connected people do monitor the forum, and, one way or another, you are likely to get a useful response from the forum, even it is is just a referral.

Notably

  • A mod support form typically can handle only a couple of attachments, and does have rich-text composition window, so you may wind up having to combine multiple screenshots into one image file, or send more than one message.
  • The TNG Forum supports both rich-text composition and attachments.
  • The TNGUsers2 discussion list does not accept attachments, so you are limited to cutting-and-pasting information from the Mod Manager into your mail composition window.

What to report

When you report a conflict to a mod author, you need to report two things:

  • The detailed mod status (from the expanded Mod Manager status cell) and
  • The candidate mods on your site.

Detailed Mod Status

You can generally take a screen shot of the target location details - really just the right-hand column shown in the screenshots near the top of this article. Some mods have a long list of target locations that it may require take at least two screenshots.

If you are using the TNGUsers2 forum, which cannot accept attachments, then you can target location details in your web browser, copy that text, and paste it into your mail composition window. That pasted text should (in a regular email composition window) look just like a screenshot. One advantage to pasting the list is that you then delete the target locations that show "Not Installed", allowing readers of the discussion list to focus on the errors.

List of Candidate Mods

The list that you gathered from the Mod Manager Analyzer and that you pared down by uninstalling and reinstalling each mod could be copied and pasted from the Analyzer, but it is probably just easier to note that mod so-and-so seems to be the culprit.

Related Links

Mod Manager

Mod Manager Controls

For Mod Developers

Technical

Developer Tools

Example Mods